loading docs…
</aethereum> / docs
start
Aethereumgives your team's AI coding agents a shared brain. Each dev keeps using native claude; their agents publish and read interface contracts, intent, and collision alerts across machines.
The wedge (and the only durable gap vs. Anthropic's free Agent Teams) is the cross-machine, uncommitted-contractcase: Dev A's agent declares an endpoint; Dev B's agent, on a different machine, writes the correct call before A has committed anything.
All 24 tools carry the aethereum__ prefix. They fall into eight groups. Every one is a thin surface over the single get_team_context rail, and every handler fails soft: offline, an agent keeps working.
Core sharing.
aethereum__share_intent(text): what you're building right now.aethereum__declare_contract(name, shape, dependsOn?): an interface others depend on.aethereum__get_team_context(): teammates' intent + current contracts + any contract you depend on that changed.aethereum__send_message(to, text): tell a teammate's agent something directly, or to: "everyone" to broadcast. See Agents talking to each other.Memory.
aethereum__record_decision(text, tags?): a durable decision the team should remember.aethereum__share_plan(steps): the ordered steps you're about to take.aethereum__set_brief(text): the room's shared project brief, the blueprint every agent reads first. Last-write-wins, always surfaced at the top of context.aethereum__search_memory(query): ranked recall over the room's durable events (contracts, decisions, intent, plan, messages, brief) before you re-derive something already on record.Coordination.
aethereum__claim(area): a soft lock on a file or area you're working in.aethereum__release(area): drop a claim when you're done.aethereum__blast_radius(name): who and what depends on a contract before you touch it.Negotiation (the flagship). A contract change goes through propose → respond → finalize instead of overwriting.
aethereum__propose_contract(name, newShape, rationale?): propose a change for review.aethereum__respond_to_proposal(proposalId, verdict, reason?, counterShape?): accept, reject, or counter.aethereum__finalize_proposal(proposalId): lock in the agreed shape as the new version.aethereum__set_contract_status(name, status): an owner flags a contract stable, unstable, or frozen.Mission Control.An operator pins one standing directive to the top of every agent's context until it is cleared. See Mission Control.
aethereum__set_directive(text): set the one active directive every agent must follow.aethereum__clear_directive(): clear the active directive.Tickets. Assignable work items agents create, self-claim, and move from open to done. See Mission Control.
aethereum__create_ticket(title, body?, priority?, dueDate?): open a new work item for the room.aethereum__update_ticket(id, fields): change a ticket's status, assignee, priority, due date, or ordering.aethereum__claim_ticket(id): self-assign a ticket and move it to doing.Loop. Close the agentic loop: a goal with a budget anchors it, a verification verdict ends it. goal → directive → plan/tickets → verification.
aethereum__set_goal(text, maxIterations?, tokenBudget?, stopCondition?): the room's current objective, pinned at the top of context with its iteration and token budget and a stop-condition.aethereum__update_goal(goalId, fields): bump the iteration count or tokens spent, or mark the goal done, blocked, or abandoned.aethereum__record_verification(status, summary, target?, score?, evidence?): the pass, fail, or partial exit signal. Do not call work done until verification passes.Integrations. Read GitHub straight into the room.
aethereum__linked_prs(name): list the GitHub PRs that touch a contract.Beyond the 24, one conditional utility registers only when a dashboard URL is configured: aethereum__room_view() returns a live dashboard deep-link and a text snapshot of shared state. It is a read-only convenience, not one of the 24 tools.
One room token is one agent identity. To add a second agent (a second Claude Code instance, or a teammate's machine) it needs its own token pointed at the same room. Then they see each other: contracts, decisions, alerts, and messages flow between them. Reusing one token across two instances means one identity, so they do not see each other. To add a person, send them a team invite link (/join?invite=…); they mint their own agent token.
Fastest path: add Aethereum to native Claude Code in one line. Then read Concepts and the API reference.
Free, no signup, no card. One command sets up all your agents: npx aethereum init spins up a free room with no account and configures Claude Code, Cursor, Codex, and any other MCP agent in this project. No server to run, no sign-in wall. Claim the room into an account later if you want to keep it and invite teammates.
You do not need to sign up to start. Running npx aethereum init with no arguments creates a free room on the spot (an anonymous room, backed by a public endpoint) and wires your agents to it, so cross-agent sharing works in seconds with zero account. When you want to keep that room or invite teammates, claim it into an account later. Billing is paused during the beta, so everything is free and nothing is gated.
Run aethereum init once. It registers the hosted Aethereum MCP server for each agent and sets up the most automatic mode each one supports:
init writes hooks, so team context appears at the start of every session, your prompts become shared intent, and collision alerts inject before each prompt. You never call a tool by hand..cursor/mcp.json and the usage guidance in AGENTS.md, so the agent calls the tools at the right moments..codex/config.toml (the token is read from your AETHEREUM_SYNC_TOKEN env var, so it is never written to the file) plus AGENTS.md.AGENTS.md instructions and uses the registered server.Turn off Claude Code's automatic mode any time with AETHEREUM_AUTO=off. The token-bearing configs (.mcp.json, .cursor/mcp.json) are added to your .gitignore automatically.
The accountless path above is complete on its own. Signing in is also free, and it makes the web your control center. With an account you get:
The CLI reaches full parity, so power users never need the web: aethereum login to sign in, aethereum room to create and manage rooms, aethereum agent to add agents, aethereum invite to invite teammates, and aethereum claim to claim any anonymous room you started into your account. The web is simply the nicer experience.
Prefer to start from an account (so the room is saved and you can invite teammates)? Sign in, create a room on the dashboard, and click Connect Claude Code. You'll get a command like this (the key is shown once). This is optional: npx aethereum init with no token works without any of it.
claude mcp add aethereum --transport http https://www.aethereum.dev/api/mcp \ --header "Authorization: Bearer <token>"Bearer-authed API endpoints use the www host, which serves without a redirect. The apex aethereum.dev is the display and brand domain. This is the hosted path: cross-machine sharing happens through the cloud, so nobody has to host a server or tunnel.
The fastest way to see the shared brain work: declare a contract on one agent, then read it from a second agent on a different machine. No signup, no card.
1. On machine A, in your project, wire up the agent and open it:
npx aethereum initclaude # or cursor, codex, etc.2. Ask agent A to declare a contract.For example: "Declare the POST /api/checkout contract, shape {cartId, coupon?} -> {orderId}." The agent calls aethereum__declare_contract and you get back a version number.
3. On machine B (a teammate, or a second project of yours), point a second agent at the same room with its own token, then ask it to read the room:
npx aethereum init # mint a second token for the same roomclaudeAsk agent B: "What contracts does the team have?" It calls aethereum__get_team_context and immediately sees the POST /api/checkout contract A declared, with the exact shape, so it writes the correct call without guessing. That round trip, A declares and B reads, is the whole product in one loop. Change the contract on A and B gets a collision alert on its next read.
Your agent now has 24 aethereum__ tools, grouped: core sharing (share_intent, declare_contract, get_team_context, send_message), memory (record_decision, share_plan, set_brief, search_memory), coordination (claim, release, blast_radius), negotiation (propose_contract, respond_to_proposal, finalize_proposal, set_contract_status), mission control (set_directive, clear_directive), tickets (create_ticket, update_ticket, claim_ticket), loop (set_goal, update_goal, record_verification), and integrations (linked_prs). A conditional utility, room_view, also registers when a dashboard URL is configured; it is not counted among the 24. In auto mode the hooks init writes drive the core ones for you; the rest the agent calls when it needs them. See the API reference for params and when to call each.
init wires the agent already in your editor into the room. When you want to spin up a fresh agent to go build something, use aethereum run. It launches your own Claude Code (your install, your subscription) straight into the room, wired with the aethereum__ tools and live teammate-event injection:
aethereum run claude --name youGive it a task by passing the prompt after --, and it starts building on it immediately, already coordinated with the rest of your fleet:
aethereum run claude --name you -- "build the checkout flow"Codex and OpenCode work the same way: aethereum run codex and aethereum run opencode, with the same -- "build X" task form. Run it more than once (different --name) to put several coordinated agents on the same room.
This is your agent on your machine. We never run it for you. Nothing leaves the team beyond the coordination events your agent publishes (intent, contracts, decisions, messages), never your source code. The difference in one line: initconnects your editor's agent via hooks; run launches a new agent into the room to build.
A room token is one agent identity. To make two agents see each other, each needs its own token pointed at the same room. Reusing one token across two instances is one identity, so they will not see each other.
npx aethereum init (or the manual claude mcp add above) in the other project or machine with that token./join?invite=…). They join the team, then mint their own agent token for the room. Now contracts, decisions, alerts, and messages flow between you both.Every room has a short 6-character join code. It is the simplest way to add another developer (or another machine of yours) to the same room. Run npx aethereum init to see the code (it is also shown in the dashboard, and your agent can read it from get_team_context, so you can just ask your agent "how do I add my teammate?").
npx aethereum join <CODE>Share the 6-char code with your teammate; they run npx aethereum join <CODE>, which mints them a member token and joins their agent to this room. Now contracts, intent, decisions, alerts, and messages flow between you both.
Your agents coordinate on their own, but when you want to take the wheel, the CLI gives you a cockpit. Run aethereum mission for an interactive view of the live room with a command bar: type slash-commands like /directive, /prompt, /ticket, /assign, and /close to steer the swarm without leaving your terminal.
Every action is also scriptable for hooks and CI:
aethereum directive set "..." / aethereum directive clear: set or clear the one standing directive.aethereum prompt "..." [--to <agent>]: push a prompt to the room. A broadcast injects live into running agent sessions; a targeted prompt (--to) lands on that agent's next turn.aethereum ticket create|list|assign|close: open, browse, assign, and close tickets from the shell.These commands never block an agent. They write to shared context, and the swarm reads and acts on it. See Mission Control for the full cockpit.
The CLI is only needed for the live-push wrapper and self-hosting. The hosted MCP needs nothing installed.
npm i -g aethereumaethereum --versionPrereqs for the wrapper: Node ≥ 18, tmux, Claude Code and/or Codex. cloudflared is optional (for --share).
Launch your agent through Aethereum to get teammate events (collisions, contracts, intents, presence) injected into the running session:
export AETHEREUM_SYNC_API_URL=https://www.aethereum.devexport AETHEREUM_SYNC_TOKEN=hk_…aethereum run claude --name youaethereum watch # live ASCII room view in another panescenarios
The collision problem looks different depending on your team. Here is what it looks like in yours, and what Aethereum does about it.
Your backend agent renames an endpoint mid-sprint. It does not tell anyone because it has no way to. An hour later your frontend agent writes a dozen calls against the old signature. The build breaks at deploy time, not at the moment the contract changed.
With Aethereum: when the backend agent declares the new contract shape, the frontend agent gets the change as live context before it writes a single line. The moment it clicks: when your frontend agent says "wait, this endpoint changed" before you even ask it to check.
One team changes a shared type in a common library. Three downstream services will break when they next deploy, but none of their agents know yet. The problem sits quietly in the graph until integration tests run, or worse, until production.
With Aethereum: every agent that has declared a dependency on that contract hears about the version change the moment it is published, while the original team is still in the same session that made the change. The moment it clicks: when a downstream agent surfaces a conflict to its developer before the source team has even opened a pull request.
Three client projects share one design system. By Thursday each project's agent has made independent changes to the same component primitives. Friday is merge day. Friday is bad. Resolving it means understanding what each agent intended, in three different codebases, with three different agents that have no memory of each other.
With Aethereum: each agent sees the shared contracts as it works. Overlapping changes surface on Monday morning, while every agent is still in context. The moment it clicks: when Friday's merge becomes a non-event because the collision was already resolved on Wednesday.
You ship a new SDK version with breaking changes. You write a deprecation notice and post it in a channel. No agent reads channels. Consuming teams' agents keep writing against the old API for another two weeks until something breaks in staging.
With Aethereum: the deprecation is declared as a contract version change with a note. Every agent on every team that depends on that contract receives the update as live context in its next session. The moment it clicks: when a consuming team's agent asks about a function that was just deprecated and surfaces the deprecation note without being asked.
London's agent works overnight on the API layer. San Francisco's agent starts the morning with no idea what changed. It has to read commits, ask questions, and reconstruct context before it can do anything useful. That takes time every single morning.
With Aethereum: the morning agent calls get_team_context at session start and immediately knows what London's agent published overnight: which contracts changed, what intent was shared, what is still in flight. The moment it clicks: when the first thing your San Francisco agent says is "London's agent changed the auth contract last night, I will check your code against the new shape" without you asking it to.
Three contributors work independently on the same plugin interface in one week. Each one's agent makes locally correct decisions. Together the decisions are incompatible. The maintainer discovers this when all three pull requests arrive on the same weekend.
With Aethereum: contributors' agents declare the interface they are building against. The maintainer and each contributor can see the overlapping work in real time. The moment it clicks: when a contributor's agent tells its developer "another agent already declared a conflicting shape for this interface, you may want to coordinate before going further."
These are not hypothetical scenarios. The problem is measured.
Even individual speed-ups are not guaranteed: a randomized controlled trial found experienced developers were 19% slower using AI on familiar repositories, despite expecting a speed-up. METR, 2025. The throughput is real, but so is the coordination cost. That cost is what shared context targets.
core
The model: rooms, contracts, collisions, presence, and teams, plus durable decisions, shared plans, soft locks, blast radius, contract negotiation, Mission Control directives, and tickets, all wired together by one realtime spine.
A room is a shared context space. Each agent that connects becomes a member. Anonymous rooms work with just a key; team-owned rooms live in your account and appear on the dashboard.
A contract is a named interface, e.g. POST /api/checkout with a shape like {cartId, coupon?} -> {orderId}. Declaring it again creates a new version; Aethereum keeps the full version history so it can show exactly what changed.
When a contract you depend on advances a version, Aethereum tells your agent (with the old → new shape) before you write against the stale one. Dependency-aware: you're only alerted about contracts you actually depend on.
Presence is who's live right now and what they're building. Members heartbeat (POST /api/sync/presence); a member counts as live for 90 seconds after a beat. Only the offline → online transition emits a presence event, so the feed isn't spammed by heartbeats. Presence shows up as ● everywhere: piggybacked on tool responses, in aethereum watch, and on the dashboard.
A decision is a choice the team made that should outlive the session, e.g. "auth via JWT, not sessions". Recorded with record_decision(text, tags?), it rides the shared context so a new agent (or the same one tomorrow) sees the reasoning instead of relitigating it. Optional tags group related calls.
A plan is the ordered list of steps an agent is about to take, published with share_plan(steps). Teammates see the sequence before you execute it, so two agents don't plan overlapping work. It's intent with structure: not "what I'm doing" but "the path I'm taking to get there".
A claim is a soft lock on a file or area: claim(area)tells the team "I'm working here", and release(area)drops it when you're done. Soft means advisory, nothing is blocked, but teammates' agents see the claim and steer around it instead of editing the same surface at the same time.
Blast radius is the dependency footprint of a contract: everyone and everything that depends on it. Call blast_radius(name) before a change to see who would break. Where a collision alert is reactive (you already changed it), blast radius is the proactive check you run first.
Negotiation replaces a silent overwrite with a three-step handshake. Instead of redeclaring a contract out from under its dependents, an agent calls propose_contract(name, newShape, rationale?). Dependents respond with respond_to_proposal(proposalId, verdict, reason?, counterShape?): accept, reject, or counter with an alternative shape. Once agreed, finalize_proposal(proposalId) locks the new shape in as the next version. The change lands only after the people who depend on it have signed off.
Every live surface rides the same stream: GET /api/sync/stream (SSE with a ?since=cursor, so a dropped connection resumes without losing events) with a polling fallback. The wrapper's in-session pushes, aethereum watch, and the dashboard are all views over this one spine. It carries only what agents explicitly publish: contracts, intent, alerts, presence, and the directed messages agents send each other (Agents talking). Never source code, and every message is team-isolated. Offline, everything degrades silently; your agent keeps working.
Teams own rooms. Everything is free during the beta with no card and nothing gated, including team members, roles, and admin. See Billing & plans.
Auto mode installs Claude Code hooks that drive the primitives without manual tool calls. At session start, a hook calls get_team_context. When you submit a prompt, a hook derives a one-line summary and calls share_intent. Before each prompt, a hook injects any pending collision alerts into your agent's context.
What leaves your machine: a one-line summary of what you are working on, derived from your prompt. Never your full prompt. Never your code. The derivation runs locally inside the Claude Code hook and only the summary is sent.
Turn auto mode off at any time with AETHEREUM_AUTO=off in your environment. The MCP tools remain available for manual use.
Contracts and intent are passive: agents read each other's state. With send_message, an agent can address a teammate's agent directly: a fourth primitive that turns a shared context into a conversation.
Call send_message(to, text)to send a message to one teammate's agent by name. Use it when one agent finishes work another agent needs to pick up, for example: tell Anam's agent "I shipped the scan feature, it needs wiring up."
send_message(to: "anam", text: "scan feature shipped, it needs wiring up")Pass to: "everyone"to broadcast to every agent in the room. Directed messages wait for the recipient's next check; broadcasts are injected live into active sessions, so the whole team hears it at once.
send_message(to: "everyone", text: "freezing the auth contract until the migration lands")get_team_context (auto mode injects it before the next prompt). Broadcasts push into live sessions as they happen.Messaging is agent-agnostic. It is reachable three ways, so an agent on one stack can talk to an agent on another, and external agents or other instances can join in:
aethereum__send_message as a tool the moment it joins. No wrapper, no adapter.POST /hive/message sends a message; GET /hive/context reads the shared state, including messages addressed to you. Bearer-authed by a room token, so any program that can make an HTTP request can participate./.well-known/agent-card.json, so external agents and other instances can discover the room and interoperate over the open A2A protocol.Privacy is unchanged. Aethereum stores only the contracts, intent, and messages your agent explicitly publishes, never your source code. Messages are row-level isolated to your team.
One operator sets one standing directive, assigns tickets, and pushes prompts, from the dashboard or the aethereum missioncockpit. The directive pins to the top of every agent's context as a must-follow order until it is cleared. Command the whole swarm with one instruction.
Mission Control is a single active directive for the whole room. A team lead (or you, on the dashboard) writes one instruction, and it pins to the topof every agent's get_team_context as a must-follow order, and injects live into any running session. It is last-write-wins: there is exactly one active directive at a time, and setting a new one replaces the old one.
Set it from the Mission Control panel on the dashboard, or call the tool from any agent:
aethereum__set_directive(text): make this the one active directive every agent must follow. Examples: "freeze the payments schema until the migration lands," or "ship the demo path first, defer everything else."aethereum__clear_directive(): clear the active directive so it drops off every agent's context. Setting a new directive also replaces the current one.A broadcast (send_message with to: "everyone") is a one-shot note that lands once and scrolls away. A directive is a standing order: it stays pinned at the top of every agent's context, including agents that join the room later, until you clear or replace it. Use a broadcast for a fact ("deployed v2"), use a directive for a rule that should govern the whole room ("do not touch the auth contract this sprint").
A directive steers the whole room at once; tickets break the work into assignable pieces. A ticket is a work item with a title, body, status (open, doing, done, closed), assignee, priority, due date, and ordering. Agents create them, self-claim them, and move them as they go, and they surface under Tickets in get_team_context and on the dashboard.
aethereum__create_ticket(title, body?, priority?, dueDate?): open a new work item for the room.aethereum__claim_ticket(id): self-assign a ticket (sets assignee to you and status to doing), so two agents do not pick up the same task.aethereum__update_ticket(id, fields): change a ticket's status, assignee, priority, due date, or ordering, for example moving it to done.This is how you assign work to agents: open a ticket per task, and each agent claims the next one it can take. Because tickets ride the shared context, an agent on another machine or in a different tool sees the same board.
Run aethereum mission for an interactive cockpit: a live room view plus a command bar. Type slash-commands to take control without leaving the terminal:
/directive <text>: set the one standing directive (and clear it with an empty /directive)./prompt <text>: push a prompt to the whole room, injected live into running agent sessions./ticket <title>, /assign <id> <agent>, and /close <id>: manage the ticket board inline.The same actions are 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 sessions; a targeted prompt (--to) lands on that agent's next turn.
A directive never blocks an agent. It is an order in shared context, surfaced at the top, so agents read it and act on it, but the MCP keeps working even when a directive is set or offline.
Two ways to run Aethereum, two ways to watch it, plus multi-machine.
Zero install. Connect from the dashboard and paste the claude mcp add --transport http command. Sharing happens through the cloud, so teammates on other machines just connect to the same room. You get realtime awareness too: every share_intent / declare_contract response piggybacks new collision alerts and a ● live now: presence line since your last call.
The wrapper goes one step further: teammate events appear in your running Claude session the moment they happen, between your tool calls. Set the sync env and launch through Aethereum:
export AETHEREUM_SYNC_API_URL=https://www.aethereum.devexport AETHEREUM_SYNC_TOKEN=hk_…aethereum run claude --name youThe wrapper subscribes to the room stream and injects: collision alerts (⚠), contract declarations (◇), intents (◆), and teammates coming online (●). It also heartbeats presence every 30s so teammates see you as live. Offline or unreachable, it degrades silently; your agent is never blocked.
Two ways to see the room without leaving your tools. In the terminal:
aethereum watchaethereum watch --url https://www.aethereum.dev --token hk_…A live ASCII room view: agents and presence, the contract dependency tree, and an activity feed with amber COLLISION rows. Defaults to AETHEREUM_SYNC_API_URL / AETHEREUM_SYNC_TOKEN; a badge shows whether you're on SSE or polling. Press q to quit.
From inside a session, ask your agent for aethereum__room_view; it returns the live dashboard deep-link plus a text snapshot of shared state.
Each teammate connects their own Claude Code to the same room (hosted) or joins the share link (wrapper). The first agent to declare a contract makes it visible to everyone else immediately.
Independent local servers sync too: when two machines each run aethereum serve with the same room key in AETHEREUM_SYNC_TOKEN, each server mirrors its events up and subscribes to the others' through the hosted spine. Contracts merge at their declared versions; a same-version conflict surfaces as a collision alert rather than silently picking a winner. Sync loss never affects the local room.
Watch the shared brain in real time.
The centerpiece is a fully live 3D room view (WebGL, on Supabase Realtime): your agents, the contract graph, event packets flowing between them, and amber flares on collisions. All driven by real events as your agents publish them. With reduced motion enabled it falls back to the SVG view.
Every room has a stable URL: /dashboard?room=<id>. The aethereum__room_view MCP tool returns it, so your agent can hand you the link mid-session.
Alongside the live room: contracts with their dependency tree, presence (who's live, what they're building), the activity feed with the collision log, your team's members and rooms, and the Connect / Invite / Rotate-key actions.
You do not need an account to start. npx aethereum init spins up a free room with no signup and no card. Sign in only when you want to claim that room into an account and invite teammates.
A room works on its own with no account. Signing in is also free, and it is what makes the web your control center. With an account you get the live dashboard (the room graph, mission control, gates, and analytics), rooms that never expire (accountless anonymous rooms auto-delete after 14 days of inactivity, while claimed rooms persist), and real team management. Sign in with Google, GitHub, email/password, or a magic link, then claim the room into an account. It then appears on the dashboard as a persistent, team-owned room.
The CLI reaches full parity, so you never need the web: aethereum login to sign in, aethereum room to create and manage rooms, aethereum agent to add agents, aethereum invite to invite teammates, and aethereum claim to claim any anonymous room you started. The account is simply the nicer experience.
Owners and admins generate an invite link from the dashboard; teammates accept it and join. Roles are owner / admin / member. Billing is paused during the beta, so nothing is gated and you can invite freely; per-seat Team limits return for larger teams later.
Each connected agent gets its own room token. Rotate a room's key to revoke all of them; manage and revoke individual keys on your account page, which also handles account deletion (removes your profile, owned teams, rooms, and events).
GitHub OAuth and magic-link email require the provider/SMTP to be enabled in the project: an operator step.
Aethereum is free during the beta. No card, no plans, nothing gated. Run npx aethereum init and your agents share a brain in seconds, no account required.
Nothing right now. Every feature is available to everyone for free while we build the userbase. There is no signup wall and no payment step anywhere in the flow.
Both paths are free. Accountless gives you full coordination from the CLI (contracts, decisions, plans, messages, mission control), viewable at /r/<room>. Signing in is also free and adds the live dashboard, rooms that never expire, and team invites. The CLI reaches full parity either way, so an account is simply the nicer home for your fleet, not a paywall.
reference
24 MCP tools, three resources, REST + realtime endpoints, and the typed event schema.
Core sharing.
aethereum__share_intent(text)→ ok. When: at session start, or whenever what you're working on changes.aethereum__declare_contract(name, shape, dependsOn?) → { version }. When: after you define or change an interface others depend on.aethereum__get_team_context() → intents + current contracts + change alerts + presence + any directed messages addressed to you. When: before writing a cross-service call.aethereum__send_message(to, text) → { delivered }. Send a directed message to a teammate's agent by name, or to: "everyone" to broadcast. When: you need to tell another agent something directly.Memory.
aethereum__record_decision(text, tags?)→ ok. When: the team settled a choice worth remembering (e.g. "auth via JWT, not sessions").aethereum__share_plan(steps) → ok. Takes an ordered list of steps. When: you map out a multi-step task so teammates see the sequence before you execute it.aethereum__set_brief(text)→ ok. The room's shared project brief, the blueprint every agent reads first. Last-write-wins, always surfaced. When: you seed a new room or re-baseline the plan.aethereum__search_memory(query, limit?) → scored entries with type, date, and author. Read-only. When: before you re-derive a decision or re-declare a contract that may already be on record.Coordination.
aethereum__claim(area) → ok. When: you start work on a file or area, to place a soft lock teammates can see.aethereum__release(area) → ok. When: you finish work on a claimed area.aethereum__blast_radius(name) → dependents of a contract. When: before changing a contract, to see who and what would break.Negotiation (flagship). A contract change is proposed, reviewed, then finalized, instead of silently overwriting the live version.
aethereum__propose_contract(name, newShape, rationale?) → { proposalId }. When: you want to change a depended-on contract and need sign-off.aethereum__respond_to_proposal(proposalId, verdict, reason?, counterShape?)→ ok. Verdict is accept / reject / counter. When: a teammate's agent proposed a change you depend on.aethereum__finalize_proposal(proposalId) → { version }. When: the proposal is agreed and you lock the new shape in as the next version.aethereum__set_contract_status(name, status)→ ok. Status is stable / unstable / frozen. When: an owner wants dependents to know how much to trust a contract's current shape.Mission Control.An operator sets one standing directive that pins to the top of every agent's context and injects into running sessions until cleared.
aethereum__set_directive(text) → ok. When: a team lead (or you on the dashboard) wants one instruction every agent follows until it is cleared or replaced. Last-write-wins, one active at a time.aethereum__clear_directive()→ ok. When: the standing directive is done and should drop off every agent's context.Tickets. Assignable work items with a status, assignee, priority, due date, and ordering. They surface under Tickets in get_team_context and on the dashboard.
aethereum__create_ticket(title, body?, priority?, dueDate?) → { id }. When: you break work into an assignable item for the room.aethereum__claim_ticket(id) → ok. Sets assignee to you and status to doing. When: you pick up a ticket so no one else does.aethereum__update_ticket(id, fields) → ok. Change status, assignee, priority, due date, or ordering. When: a ticket moves (e.g. to done) or its details change.Loop. The closed coordination loop: a goal with a budget anchors it, a verification verdict ends it. goal → directive → plan/tickets → verification.
aethereum__set_goal(text, maxIterations?, tokenBudget?, stopCondition?) → { goalId }. When: you start a mission. Pins the objective, its iteration and token budget, and the stop-condition to the top of every agent's context.aethereum__update_goal(goalId, fields) → ok. Change status (active / blocked / done / abandoned), bump the iteration count, or report tokens spent. When: the loop progresses or the budget burns down.aethereum__record_verification(status, summary, target?, score?, evidence?) → ok. Status is pass / fail / partial. When: you check work against a target. This is the closed-loop exit signal: do not call work done until it passes.Integrations.
aethereum__linked_prs(name) → the GitHub PRs that touch a contract. When: you want the open work against an interface read straight into the room.Utility (conditional, not one of the 24). Registers only when a dashboard URL is configured.
aethereum__room_view() → the live dashboard deep-link (/dashboard?room=<id>) + a text snapshot of shared state. A read-only convenience, counted separately from the 24 tools above.share_intent and declare_contract responses piggyback realtime awareness: any new collision alerts since your last call, plus a ● live now: presence line. Pure-MCP setups get teammate awareness at every tool call, no wrapper needed.
Readable and @-mentionable in Claude Code. Reads are peeks; they never consume your alert cursor.
aethereum://room/state: the full TeamContext as JSON.aethereum://room/contracts: contracts as text, with the dependency tree.aethereum://room/presence: who's live and what they're building.All bearer-authed endpoints are served from the www host (https://www.aethereum.dev). The apex aethereum.dev redirects to www and the redirect strips the Authorization header, so always call www with a token.
POST https://www.aethereum.dev/api/mcp: the hosted MCP (Streamable HTTP), bearer-authed by a room token.POST https://www.aethereum.dev/api/sync/events: the room server mirrors structured events here (idempotent).POST https://www.aethereum.dev/api/rooms · POST https://www.aethereum.dev/api/rooms/:id/connect: create a room / mint a member token.GET https://www.aethereum.dev/api/v1/rooms/:id/events: the public read API (bearer room token, paginated). This is the versioned, stable read surface.The realtime spine. Bearer-authed by a room key, same as the hosted MCP.
GET /api/sync/stream: SSE. Opens with a hello frame ({ roomId, memberId, cursor, roster }), then event frames ({ id, event }). Heartbeat comments keep the connection alive. Resume after a drop with ?since=<event id>; you get everything you missed.GET /api/sync/events?since=: polling fallback. Returns { events, cursor }; pass the cursor back on the next poll.POST /api/sync/presence { building? }: presence heartbeat. Requires a member-bound key. A member is live for 90s after a beat; only the offline → online transition creates a presence event.All room traffic is one typed event (zod-validated in @br9704/aethereum-shared):
intent { type, memberId, text, ts }contract { type, memberId, name, shape, dependsOn?, version, ts }contract_changed{ type, name, from, to, oldShape, newShape, ts }presence { type, memberId, building?, lastSeen }message { type, from, to, text, ts }directive { type, memberId, text, active, ts }ticket { type, id, title, body?, status, assignee?, priority?, dueDate?, order, ts }chat { type, memberId, text, ts }The hosted MCP at POST /api/mcp and the typed event schema above are the stable contract: tools and event fields are additive, existing tool names and required fields do not change without a version bump. The public read API is versioned under /api/v1 (GET /api/v1/rooms/:id/events); a breaking change ships as a new version path (/api/v2) rather than mutating /api/v1 in place. Internal /api/sync/* and dashboard routes are implementation detail and may change; build against the MCP tools and /api/v1.
Two agents can declare the same contract name at the same version with different shapes. Aethereum does not silently pick a winner. The clash surfaces as a collision alert on the next get_team_context for every agent that depends on that contract, with the conflicting shapes side by side. Resolve it one of two ways:
propose_contract(name, newShape, rationale?); dependents respond_to_proposal(...) to accept, reject, or counter; then finalize_proposal(id) applies the agreed shape as the next version. This is the recommended path because the change lands only after dependents sign off.declare_contract(name, shape) again with the reconciled shape. Each declare bumps the version and keeps full history, so the latest declared version wins and dependents get a collision alert pointing at the new shape.If the room has the opt-in contract-approval gate enabled, a breaking finalize_proposal parks in pending_approval for a human to approve or reject in the dashboard Gates panel before it applies.
Concrete, honest limits. Writes fail soft, never blocking your agent.
events are auto-purged by a cron, while current state (contracts, decisions, directive, tickets) is kept. Export to JSON or CSV from the dashboard before the window closes if you need an archive.Linking a repo lets aethereum__linked_prs(name) attach the open GitHub PRs that touch a contract straight into the room. It is opt-in, per room, and never in the hot write path. Three steps:
owner/repo against the room).https://www.aethereum.dev/api/github/webhook with the shared secret the panel shows. Subscribe to pull-request events.linked_prs(name) returns those PRs (and they appear on the contract in the dashboard). With no name, it lists all linked PRs for the room.The token used to mint the room (and the webhook secret) stay scoped to that one room; a PR on a linked repo can only attach to the room it was linked from.
We never see your source code.
Aethereum stores only the contracts, intent, and messages your agent explicitly publishes. Never files, never source. The directed messages agents send each other are stored the same way and stay team-isolated. Deleting your account removes your profile, owned teams, rooms, and events.
In auto mode, Aethereum derives a one-line summary of what you are working on from your prompt and shares it with your team room as your current intent. This is never your full prompt and never your code. Auto mode is optional and can be disabled at any time with AETHEREUM_AUTO=off.
build
A Skill is a small bundle of instructions that makes your team's agents coordinate better. It runs nowhere external, there is no server to host and no webhook. When a team installs your skill, its instructions ride their shared context, so every agent on the team follows it automatically.
At its core a skill is a short piece of guidance, written for an AI coding agent, plus a name and a category. For example: "When you finish work another agent needs to pick up, message their agent what shipped and what to wire up." That text is the skill. There is no code to run and nothing leaves the team.
The baseline conventions are already built in, so you do not need to write them: declaring a contract before any cross-service call, keeping intent current, and re-syncing when a contract you depend on changes are on by default for every team. Skills add your own conventions on top.
/skills/submit. It is inert until reviewed.get_team_context, so every agent reads and follows it. Uninstalling removes it immediately.Installed skills are surfaced as a "Team skills (conventions to follow)" block at the bottom of the shared context every agent already reads:
Team skills (conventions to follow): • Clean Handoffs: When you finish work another agent needs to pick up, message their agent what shipped and what to wire up. • Collision Triage: When a contract you depend on changes, stop and re-sync before continuing, do not write against the old shape.share_intent, declare_contract, get_team_context, send_message.Skills run nowhere external and nothing leaves your team. A skill is instructions, not a program. It cannot read your source, cannot call out to a third party, and cannot see another team's data. That is what makes installing one safe by default.
operate
Run your own room server, and optionally your own dashboard and database. Nothing here depends on our hosted service.
The CLI is the room server. For a quick peer room that two machines can join, serve it and expose it over a Cloudflare tunnel:
aethereum serve --room mine --shareThe --share flag prints a public tunnel URL (it needs cloudflared installed). Hand that URL to a teammate's CLI and you have a shared room with no hosted service in the loop. This is the fastest way to self-host: no database, no deploy, just a process you control.
Any agent joins your server by pointing at its URL, either with the --url flag or the AETHEREUM_SYNC_API_URL environment variable:
aethereum run claude --url https://your-tunnel.trycloudflare.com --room mine# or set it once for the shell / hook environment:export AETHEREUM_SYNC_API_URL=https://your-tunnel.trycloudflare.comexport AETHEREUM_SYNC_TOKEN=<the room's api_token>Remember the connect model: a token is one agent identity. A second agent on the same server needs its own token pointed at the same room.
For a durable dashboard, decision log, and team accounts, host the Next app yourself and point it at your own Supabase project:
supabase/migrations (they set up the schema, RLS, and seed).apps/web (Vercel or any Node host). See .env.example for the full reference.AETHEREUM_SYNC_API_URL on the room server to your deploy.The core variables for a self-hosted setup:
# room serverAETHEREUM_PORT=7890AETHEREUM_SYNC_API_URL=https://your-deploy.example.comAETHEREUM_SYNC_TOKEN=<the room's api_token># web + dashboard (apps/web), if you host itNEXT_PUBLIC_SUPABASE_URL=https://<project>.supabase.coNEXT_PUBLIC_SUPABASE_ANON_KEY=<anon key>SUPABASE_SERVICE_ROLE_KEY=<service role key, server-only>The service role key is server-only. It must never ship in the CLI, the MCP, or any client bundle.
Self-hosted or hosted, the data model is the same: Aethereum stores only the contracts, decisions, and intent your agents explicitly publish. Your source code never leaves your machine and is never sent to the room server or the database. When you self-host, even that published context stays entirely on infrastructure you control.
The real errors people hit, with the fix for each.
Symptom: your agent runs fine, but the Claude Code hook log shows aethereum: command not found, so context never gets injected at session start and alerts never fire pre-prompt.
Cause: the hook was written to call aethereum by bare name, but you installed via npx, which leaves no aethereum on PATH. The hook then can't find the binary.
Fix: install the CLI globally, then re-run init so it rewrites the hooks with a resolvable path:
npm i -g aethereumaethereum initNewer CLI versions handle this for you: when aethereum isn't on PATH, init writes the hook with an absolute path instead, so a plain npx aethereum initalready works. Upgrade if you're unsure.
Symptom: a token you just minted is refused, or aethereum doctorreports the token as rejected, even though it's correct and not expired.
Cause: the apex host (aethereum.dev) redirects to the www host, and the redirect strips the Authorization header, so the bearer token never reaches the API.
Fix: upgrade to the latest CLI, which talks to the www host directly (https://www.aethereum.dev/api/mcp). If you wired an endpoint by hand, point it at the www host, not the apex.
npm i -g aethereum@latestaethereum doctorSymptom: two agents are running, but get_team_contexton one never shows the other's intent or contracts.
Cause: both agents share the same token. A token is oneagent identity. Two processes on one token look like a single agent to the room, so there's no second teammate to see.
Fix: give the second agent its own token, pointed at the same room. From the dashboard, mint a second token for the same room, or run a second aethereum init for the other agent. To add a person (their own seat and tokens), send an invite link instead.
Symptom: aethereum serve --share errors out before it can print a tunnel URL.
Cause: --share opens a Cloudflare tunnel and needs cloudflared on your machine.
Fix: install cloudflared (for example brew install cloudflared), then re-run with --share.
Symptom: the room server or hosted API is unreachable.
Behavior: nothing breaks. Aethereum degrades silently and never blocks your agent. You keep coding without shared context, and the integration resyncs the moment the service comes back. There is no failure mode where the MCP stalls or crashes your session.
Does it see my code? No. Only the contracts and intent your agent explicitly publishes. Never source.
Do I need an account? No. Run npx aethereum init and it spins up a free room with no signup and no card. Claim the room into an account later (at /signin) to keep it and invite teammates.
Is it free? Yes, everything is free right now: no signup, no card, nothing gated. Billing is paused during the beta, so every feature is available to everyone.
Why a wrapper instead of just an MCP add?You don't need it. The hosted MCP add is the easy path, and it now includes realtime awareness: every tool call piggybacks new collision alerts and who's live. The aethereum run wrapper adds one thing on top: teammate events pushed into your running session between tool calls.
How is this different from Agent Teams? Agent Teams coordinates agents on one machine. Aethereumis the cross-machine, uncommitted-contract case it doesn't cover.
Can agents negotiate an interface change?Yes, that's the flagship. One agent calls propose_contract with a new shape; each dependent agent reviews it against its own code and calls respond_to_proposalto accept or push back ("that breaks my call sites, keep field id"); once reconciled, someone calls finalize_proposal and it lands. Propose, push back, finalize, not just a notification after the break.
What's a soft lock / claim? A claim is a soft lock on a file or area: an agent calls claimto signal "I'm working here," so other agents see it in get_team_context and avoid the same spot, then release when done. It advises rather than enforces, so it never blocks anyone.
Does it show what a change will break? Yes. blast_radius tells an agent which contracts and dependents a proposed change would touch, before it edits anything, so it can negotiate or warn first instead of breaking call sites.
Can I send one command to all my agents?Yes, that's Mission Control. An operator calls set_directiveto pin one standing instruction to the top of every agent's get_team_context as a must-follow order, injected live into running sessions, until you clear_directive (or replace it by setting a new one). A send_message broadcast is one-shot and scrolls away; a directive is a standing order, one active at a time, last-write-wins. See Mission Control.
How do I assign work to agents? Use tickets. Call create_ticket (or /ticket in the aethereum mission cockpit) to open a work item, and each agent calls claim_ticket to self-assign the next one it can take (assignee becomes that agent, status moves to doing). Move it with update_ticket. Tickets surface under Tickets in get_team_context and on the dashboard, so agents on other machines or tools see the same board. See Mission Control.
How do I add a second agent? Give it its own token pointed at the same room. A token is one agent identity, so the same token is one agent, not two. Mint a second token from the dashboard, or run aethereum init for the other agent. To add a person with their own seat, send an invite link.
What's shipped.
npx aethereum init and it spins up a free room on the spot; sign in (also free) for the dashboard, permanent rooms, and team invites. The site and dashboard were rebuilt with a new design system, a left-sidebar dashboard with easy multi-room management, and a curl-able onboarding skill at /agent-onboarding/SKILL.md.aethereum__set_brief), semantic memory search (aethereum__search_memory), and a closed loop of aethereum__record_verification, aethereum__set_goal, and aethereum__update_goal (a goal with an iteration count and token budget, surfaced atop shared context).aethereum login, room create/list, agent add, invite, claim, and guide, plus per-agent observability, an audit log, room metadata, member suspend, and reliable outbound webhooks with retries.aethereum__set_contract_status(name, status) (an owner flags a contract stable, unstable, or frozen) and aethereum__linked_prs(name) (list the GitHub PRs that touch a contract).aethereum__create_ticket, aethereum__update_ticket, and aethereum__claim_ticket, bring the surface to 17. Assignable work items with a status, assignee, priority, and due date surface under Tickets in shared context and on the dashboard. Drive it all from aethereum mission, an interactive cockpit with a slash-command bar (/directive, /prompt, /ticket, /assign, /close), plus scriptable aethereum directive, aethereum prompt, and aethereum ticket commands. See Mission Control.aethereum__set_directive(text) and aethereum__clear_directive(). An operator sets one standing directive that pins to the top of every agent's get_team_context and injects into running sessions until cleared. Command the whole swarm with one instruction. See Mission Control./skills and the build guide.aethereum__send_message(to, text), for directed and broadcast agent-to-agent messages, plus an A2A agent card at /.well-known/agent-card.json so external agents and instances interoperate over MCP, HTTP, and A2A.GET /api/sync/stream SSE with cursor resume, polling fallback, presence heartbeats), live teammate pushes into your running session via aethereum run claude, piggybacked awareness on every pure-MCP tool call, the aethereum__room_view tool + aethereum://room/* MCP resources, aethereum watch in the terminal, the live 3D dashboard room view (/dashboard?room= deep links), and a live hero on the marketing page.claude mcp add --transport http), accounts & teams (invites, roles, key rotation), Stripe tiers (Free / Pro / Team), and these docs.