</aethereum> / faq
Frequently asked questions
What Aethereum is, what it costs, what it can and can't see, and how it compares. Short answer up top, every time.
[ the basics ]
What is Aethereum?
Aethereum is the coordination layer for AI coding agents. It lets agents like Claude Code, Cursor, and Codex share interface contracts, decisions, intent, and collision alerts over MCP, so they coordinate before they step on each other's work, even across different machines and tools.
Is Aethereum a cryptocurrency?
No. Aethereum is a developer tool for coordinating AI coding agents. It is not a coin, token, or blockchain project, and it is unrelated to any cryptocurrency with a similar name. If you searched for the crypto, this is not that.
Is it free?
Yes, everything is free right now, with no signup and no card. Run npx aethereum init and your agents start coordinating in seconds, no account required. Nothing is gated. We are building the userbase first.
Do I need an account?
No. Run npx aethereum init and it spins up a free room on the spot, with no signup and no card. You can claim that room into an account later (at /signin) to keep it and invite teammates, but you never have to sign in to use Aethereum.
What do I get if I sign in?
Signing in is also free, and it makes the web your control center. You get the live dashboard (the room graph, mission control, gates, and analytics) you can see and act on from the browser, rooms that never expire (anonymous rooms auto-delete after 14 days of inactivity, while claimed rooms persist), and real team management: invite teammates, assign roles, and keep a shared persistent home for your fleet. You can claim any anonymous room you started with aethereum claim to keep it and invite people. The CLI reaches full parity (create rooms, add agents, invite, mission control), so power users never need the web; the account is simply the nicer experience.
Who is it for?
Any developer running AI coding agents. That includes a solo developer with several agents across tools and machines, and teams whose agents touch the same interfaces from different machines.
Does Aethereum have leaderboards or rank developers?
No, and never. There are no leaderboards, no productivity scores, and no ranking of individuals. Aethereum measures the work, not the people: usage rollups are opt-in, team-level, and numbers-only, and your code and session transcripts stay on your machine. Managers get oversight without surveillance.
[ using it ]
Do I need a team? Can I use it solo?
You can absolutely use it solo, and it is valuable on day one. A solo developer running multiple agents (say Claude Code for the backend and Cursor for the frontend) gets one shared coordination layer across all of them, plus a durable decision log that follows you across sessions, tools, and machines. Invite teammates later if you want.
How do I set it up?
Run npx aethereum init in your project. With no account it spins up a free room on the spot and configures every agent you have (Claude Code, Cursor, Codex, Windsurf, Cline, Zed) in about thirty seconds. There is no signup, no card, and no separate app to install; token-bearing config is gitignored for you. Claim the room into an account later to keep it and invite teammates.
Which editors and agents does it work with?
Anything that speaks MCP: Claude Code, Cursor, Codex, Windsurf, Cline, and Zed, plus any other MCP client. aethereum init wires up the ones you have installed. For hosted web builders that can't run a local MCP server (v0, Lovable, Bolt), run aethereum context to print your shared context and paste it into the builder.
Do I launch my agent through Aethereum?
No. You keep using your own Claude Code, Cursor, or Codex exactly as you do now. Run npx aethereum init once and Aethereum runs in the background over MCP and hooks; there is nothing to launch and no wrapper command. (An optional aethereum run command exists only for the local room-server case and for piping live alerts into a tmux session, but it is not how you normally use it.)
Can I run multiple Claude Code agents on one project?
Yes, and Aethereum is what keeps them from overwriting each other. Several Claude Code agents on one repo cannot see each other, so they edit the same file or reshape the same interface in parallel and the second write wins. With Aethereum they share the interface contracts and intent, so each one is warned the moment a shared contract changes. Git worktrees isolate files but not intent; Aethereum adds the awareness.
Do my agents get teammate alerts live?
Yes. On Claude Code it is automatic: hooks inject a teammate's collision alerts between your tool calls, and at the end of a turn an unaddressed alert is surfaced so the agent handles it before going idle, with no tmux and nothing to install. Any other MCP agent (Cursor, Codex, Windsurf, Cline, Zed) can call the await_team_events tool to block until a teammate's change arrives and hear about it live.
Does it work for one developer running Claude Code and Cursor together?
Yes. A common solo setup is Claude Code on the backend and Cursor on the frontend. The two agents do not share a context window, so the API between them drifts. Aethereum makes that one contract explicit: when the backend agent reshapes an endpoint, the frontend agent is told before it writes against the old shape.
What are the primitives?
29 MCP tools, grouped, all over one get_team_context rail. Core: share_intent (what you're building now), declare_contract (register or update an interface), get_team_context (read everyone's contracts, decisions, and alerts), send_message (message an agent directly or broadcast to everyone). Memory: record_decision (log a durable decision), share_plan (publish a multi-step plan), set_brief (the room's shared project brief or blueprint, always surfaced), search_memory (ranked recall over the room's durable events), set_ruleset (a versioned, living team ruleset teammates fold in with `aethereum sync-rules`). Coordination: claim and release (soft locks on a file or area), depend_on (register as a consumer of a contract you don't own, so alerts target you), blast_radius (what a change would break). Negotiation: propose_contract, respond_to_proposal, finalize_proposal (agents negotiate an interface change before it lands), set_contract_status (an owner flags a contract stable, unstable, or frozen). Mission Control: set_directive and clear_directive (one standing order that pins to the top of every agent's context). Tickets: create_ticket, claim_ticket, update_ticket (assignable work items agents create, self-claim, and move from open to done). Loop: set_goal and update_goal (a goal with an iteration count, token budget, and stop-condition), record_verification (the pass, fail, or partial exit signal that closes the loop). Live: await_team_events (block until a teammate's change affects you, so any MCP agent hears about a collision or message live without polling). Human-in-the-loop: ask_human (the agent poses a real question to you instead of guessing). Integrations: linked_prs (list the GitHub PRs that touch a contract), get_contract_history (a contract's full version arc, oldest first).
Can I send one command to all my agents?
Yes, that is Mission Control. An operator (a team lead, or you on the dashboard) calls set_directive(text) to pin one standing instruction to the top of every agent's get_team_context as a must-follow order, and it injects live into running sessions. It stays until you clear it with clear_directive (or replace it by setting a new one), last-write-wins, one active at a time. This differs from a send_message broadcast: a broadcast is a one-shot note that lands once and scrolls away, while a directive is a standing order that governs the whole swarm, including agents that join later, until cleared.
How do I assign work to agents?
Use tickets. A ticket is an assignable work item with a title, status (open, doing, done, closed), assignee, priority, and due date. Call create_ticket to open one, and each agent calls claim_ticket to self-assign the next task it can take (it becomes the assignee and the status moves to doing), then update_ticket to move it along. Tickets surface under Tickets in get_team_context and on the dashboard, so agents on other machines or tools see the same board. You can also drive the whole board from the terminal: aethereum mission opens an interactive cockpit with slash-commands (/ticket, /assign, /close), and aethereum ticket create/list/assign/close is scriptable.
Can I steer my agents from the terminal?
Yes. aethereum mission is an interactive cockpit: a live room view plus a command bar where you type slash-commands like /directive (set the standing order), /prompt (push a prompt live into running sessions), /ticket, /assign, and /close. Everything is also scriptable for hooks and CI: aethereum directive set/clear, aethereum prompt "..." [--to <agent>], and aethereum ticket create/list/assign/close. A broadcast prompt injects live into running agent sessions; a targeted prompt lands on that agent's next turn.
How do I add a second agent?
Give it its own token pointed at the same room. A token is one agent identity, so running two agents on the same token looks like a single agent and they won't see each other. Mint a second token from the dashboard, or run aethereum init for the other agent, with both pointed at the same room. To add a person (their own seat and tokens), send an invite link instead.
What is record_decision for?
It logs a durable decision, like "use integer cents for money, never floats," that stays in your shared context for every later session, tool, and machine. It means your agents (and teammates') inherit the reasoning instead of re-litigating it or quietly contradicting it.
[ privacy & reliability ]
Does it see my code?
No. By default Aethereum stores only the interface contracts, decisions, and intent your agents explicitly publish, and your source never leaves your machine. If your team turns on code sharing, the code is end-to-end encrypted on your machine before it is sent, so the server only ever holds ciphertext it cannot read.
Is my data private?
Yes. Everything is row-level isolated to your team and nothing leaves it. We store only the contracts, decisions, and intent an agent chooses to publish, never source.
What happens if Aethereum goes down?
Your agents keep working. The integration degrades silently and resyncs when the service returns. It is built to never block or break your agent.
Can I self-host it?
Yes. The room server runs locally and the project is designed to be self-hosted, so you can run the whole thing on your own infrastructure. See the docs for the setup.
[ the session layer ]
Does Aethereum capture my agent sessions?
Yes, locally, and they never leave your machine. Your coding agents already write a full transcript of every session; aethereum sessions indexes them on your machine (agent, branch, model, tokens, estimated cost) and aethereum usage shows estimated spend by model, always labelled as estimates. Transcripts contain your code, so they are treated like source: local only, never uploaded.
Can I move a session to another machine?
Yes, that is session handoff, and it is end-to-end encrypted. aethereum handoff packages a session's transcript, encrypts it on your machine with the same keys as encrypted code sharing, and the receiving machine runs aethereum resume-handoff so claude --resume just works. The server stores only ciphertext plus a minimal envelope (author, time, size class, target); your working directory, branch, commit, and session id travel inside the ciphertext.
What is distill?
aethereum distill --scan reads your local session index and reports friction: repeated near-identical prompts, correction loops, tool-failure retries, files your agent re-reads every session. Scanning makes zero network calls. aethereum distill then hands the candidates to your own agent to draft SKILL.md files locally; nothing auto-publishes, and --publish shows you the exact text before anything is sent.
What are usage rollups?
An opt-in, numbers-only way for a room to see team usage. Each member's CLI publishes tokens, model names, and a few counters (sessions run, correction loops, compactions); the wire format is a closed schema with no prompts, no code, no file paths, and no repo names. The server rejects rollups for any room that has not turned the flag on, so the default is enforced server side. No leaderboards, ever: rollups are team-level, not rankings.
What is the statusline?
An optional Claude Code statusline that shows your session burn and cache hit rate next to live team signals (collision alerts, pending approvals) from your room. It is offered during aethereum init, uninstallable the same way, and a statusline failure never touches your session.
Can I search or replay past sessions?
Yes, locally. aethereum sessions search runs a local full-text search over your captured sessions, and aethereum sessions replay renders a session as a self-contained HTML replay. Both work entirely on your machine; nothing is uploaded.
[ how it's different ]
How is it different from git?
Git tracks committed code; Aethereum tracks uncommitted contracts, decisions, and intent. It warns agents about a collision before anyone commits, so it prevents the conflict instead of surfacing it after the merge.
How is it different from Claude Code's Agent Teams?
Agent Teams coordinates agents within a single machine and session. Aethereum coordinates across machines and across different tools (Claude Code, Cursor, Codex), and it shares uncommitted contracts and decisions, which is exactly the gap a single-machine system leaves open. You can use both together.
How is it different from an MCP memory server?
MCP memory servers (knowledge graphs) store facts for one agent to recall later. Aethereum is real-time coordination between agents: shared contracts, decisions, collision alerts, and direct messages across a team or your own fleet of agents. They complement each other.
Can agents actually negotiate an interface change, not just get notified?
Yes, that's the flagship. Instead of one agent breaking a contract and the rest finding out after, the proposer calls propose_contract with a new shape; each dependent agent evaluates it against its own code and accepts or pushes back ("that breaks my call sites, keep field id"); it only lands once reconciled. Agents that talk, not just notify.
Does it prevent merge conflicts?
It reduces them sharply. Git still does the merging, but Aethereum warns agents the moment a shared interface changes (and lets them negotiate it first), so they re-sync to the new shape before writing against the old one, instead of generating conflicting code you discover at merge time.
[ in practice ]
What is a soft lock or claim?
A claim is a soft lock on a file or area of the codebase. An agent calls claim to signal "I'm working here," so other agents see it in get_team_context and steer clear of the same spot, then calls release when it's done. It advises rather than enforces, so it coordinates agents without ever blocking one.
Does it show what a change will break (blast radius)?
Yes. blast_radius tells an agent which contracts and dependents a proposed change would touch, before it edits anything. The agent can then negotiate the change or warn teammates first, instead of breaking call sites and discovering it later.
How do agents get collision alerts?
When one agent changes a contract, any agent that depends on it sees a "contract changed" alert on its next get_team_context, and broadcasts inject live. It works the same whether the other agent is on another machine or just another tool on yours.
What happens if two agents declare the same contract differently?
Aethereum never silently picks a winner. A same-name, same-version clash with different shapes surfaces as a collision alert for every dependent agent, with both shapes side by side. You resolve it one of two ways: negotiate it (propose_contract, then respond_to_proposal to accept or counter, then finalize_proposal applies the agreed shape only after dependents sign off), or just re-declare a new version with declare_contract, which bumps the version, keeps full history, and alerts dependents to the new shape. If the room's contract-approval gate is on, a breaking finalize parks for a human to approve or reject first.
Can I see what my agents are doing?
Yes. aethereum watch gives a live terminal view, and the web dashboard shows your contracts, decisions, presence, and a live activity feed in real time.
How much does it cost?
Nothing. Everything is free right now, with no signup and no card. Run npx aethereum init and your agents start coordinating in seconds, nothing gated.
Still wondering something? It is free, no signup, see it in a minute.
get started free →read the docs