Documentation

Quickstart

Three commands, about two minutes, no account and no card. At the end, two AI agents will be reading each other's interface contracts while you keep working in the terminal you already use.

Step 0. See it work before you install anything

This runs a real two-agent collision against the live service and narrates it. It takes about ten seconds, needs no account, and writes nothing to your project.

npx aethereum demo

Two agents declare the same endpoint with different shapes, and the second one gets warned. That warning, arriving before anyone commits anything, is the entire product. If you like what you see, carry on to step 1.

Step 1. Wire up your project

Run this in the root of the project you are working on, the folder with your package.json or .git in it.

npx aethereum init

It creates a free room, wires every AI coding tool it can find in this project, and prints a receipt that looks like this:

──────────────────────────────────────────────────────────
  Your room is LIVE: checkout-api  (free, no account)
  Bring a teammate in     npx aethereum join K3M7QP
  See it live
    terminal    aethereum
    browser     https://www.aethereum.dev/r/<room-id>?t=<key>
    desktop     aethereum app
  Wired for     claude ✓ · cursor ✓ · codex (install to use)
──────────────────────────────────────────────────────────

Two things on that receipt matter right now. The six-character join code (K3M7QP above) is how a teammate gets into the same room. The browser link is your live room view, and it works without signing in.

Step 2. Open your agent the way you always do

There is no new terminal to learn and no wrapper to run. Open Claude Code, Cursor, Codex, or whatever you already use, in this project, exactly as before.

claude

The coordination happens underneath. On Claude Code the team's current state is injected at the start of every session, your prompts become shared intent, and a teammate's collision alerts arrive between your tool calls. You do not call anything by hand.

Now give your agent something to share. Type this into your agent, in plain English:

Declare the POST /api/checkout contract:
{ cartId, coupon? } -> { orderId }

It calls declare_contractand answers with a version number. That contract is now the team's, live, before a single line is committed.

Step 3. Bring in the second agent

On the other machine, or in another project of your own, run the join code from step 1. Do not run plain init there: that would mint a different room and the two would never see each other.

npx aethereum join K3M7QP

Then open the agent there and ask it:

What contracts does the team have?

It calls get_team_context and sees POST /api/checkout with the exact shape, so it writes the correct call instead of guessing. Change the shape on the first machine and the second one gets a collision alert on its next read. That round trip is the whole loop.

Did it work?

One command tells you the state of every surface in this project:

npx aethereum status

Green on the room row means you are connected. Anything red prints the exact command that repairs it, and aethereum status --fix repairs all of them at once. If a row confuses you, every state is listed in reading aethereum status.

Where to go next

You now have a working room. The rest of the docs are optional depth, in the order most people want it: what init actually did to your project, what each tool is for in plain language, the ideas behind it (rooms, contracts, collisions), and what to do when something breaks.

Overview

Aethereumis a shared brain for your team's AI coding agents. Everyone keeps using the tool they already use. Underneath, their agents share interface contracts, what they are working on, and warnings about each other, across machines, before anything is committed.

The problem it solves

Two developers, two machines, two agents. One agent defines POST /api/checkout and starts building against it. The other agent, forty minutes away from finding out, writes a call with the wrong shape. Nothing is committed yet, so there is nothing for either of them to read. They find out at integration time.

The fix is not another repo convention. It is a live room both agents are in: the moment one declares the contract, the other can see it, and the moment one changes it, the other is warned. That cross-machine, not-yet-committed case is the whole point.

How it works, in three lines

• One command wires your project. npx aethereum init creates a free room and connects every AI coding tool it finds. No account, no card, no server to run.
• Your agents get about thirty tools.They publish what they are building, register the interfaces they own, and read the room before writing code that touches somebody else's work. On Claude Code the important ones fire automatically.
• You keep working exactly as before. Same editor, same terminal, same way of launching your agent. There is a browser view and a desktop app if you want them, and you never have to open either.

What it is not

It is not a hosted agent: we never run your agent for you, and it stays on your machine, on your subscription. It is not a code host: by default nothing but the contracts, intent, decisions, and messages your agent explicitly publishes ever leaves your machine, and source code is not among them. It is not a gate: every tool fails soft, so an agent offline or rate-limited simply carries on.

Start here

The quickstart gets you from nothing to two agents reading each other in about two minutes. After that: what each tool is for, what init did to your project, and the ideas behind rooms, contracts, and collisions.

Setup

What npx aethereum init writes, how to add a second agent or a teammate, and how to turn any of it off. If you have not run it yet, start at the quickstart.

You keep the terminal you already have

This is the part people expect to be harder than it is. There is no Aethereum terminal, no wrapper you have to remember, and no new way to launch your agent. You open Claude Code, Cursor, Codex, or whatever you use, in your project, the way you always did. Nothing about your workflow changes.

What changes is that your agent now has a shared room behind it. On Claude Code that happens with no effort at all, because initwrote hooks: the team's state is injected at the start of every session, your prompts become shared intent, and a teammate's collision alerts arrive between your tool calls. On the other tools the coordination rules land in AGENTS.md and the agent calls the tools itself.

The optional extras exist for people who want them. aethereum on its own is a live room view in your terminal, aethereum open is the same room in a browser, and aethereum app is the desktop app that puts real terminals beside it. You never have to touch any of the three.

What init actually does to your project

It is all local files in the project you ran it in, plus one entry in a config file in your home directory. Nothing is installed globally and nothing runs on a machine you did not ask.

• Creates a free room if this project does not have one, and records it in ~/.aethereum/config.json keyed by this directory. Running init again in the same project reuses that room rather than minting a new one.
• Writes .mcp.json with the hosted MCP server and your room key, and adds it to .gitignore alongside .cursor/mcp.json, .vscode/mcp.json, and opencode.json. If .mcp.json is already tracked by git, it says so loudly, because a .gitignore entry does nothing for a file already in history.
• Wires Claude Code by merging six hooks into .claude/settings.json: session start, prompt, post tool use, stop, subagent start, subagent stop. This is what makes the automatic mode automatic.
• Wires Cursor and Codex with both an MCP entry and hooks (.cursor/mcp.json plus .cursor/hooks.json, .codex/config.toml plus .codex/hooks.json). Codex reads its key from a per-project environment variable so two projects never collide, and init prints the exact export line to paste into your shell.
• Wires anything else it can find, but only if it is already installed: Windsurf, Cline, Zed, opencode, Gemini CLI, GitHub Copilot in VS Code, and Amp. Tools it cannot detect are listed as skipped, and installing one and re-running init wires it.
• Writes AGENTS.md and GEMINI.md with the coordination loop, plus Cursor rules. This is how a tool with no hook support still knows what to do.
• Adds a pre-commit hook (only in a git repository) that runs aethereum check. It is advisory by default and never blocks a commit; add --strict to the hook to make it enforce.
• Starts a small delivery daemonso a teammate's events reach you without you asking. On macOS it also offers to start on login. Neither can execute anything: running work is a separate, explicit opt-in (the control plane).

Want the full receipt rather than the summary? Run npx aethereum init --verbose, which prints one line per file it touched.

Useful init options

• --yes runs it non-interactively, for scripts and CI.
• --new-room forces a fresh room in a project that already has one.
• --token <key> wires this project to an existing room by key instead of creating one.
• --prd <file> or --doc <file>(repeatable) seeds the room's project brief from files you already have, so every agent starts on the same plan. --no-brief skips the brief entirely.
• --no-login skips the sign-in offer, --no-open skips opening the browser, and --no-service skips the login autostart and remembers that you said no.

Adding a second agent

A room key is one agent identity. Two agents sharing one key look like a single agent to the room, so they will not see each other. Each one needs its own key pointed at the same room. There are two ways to get one.

Another machine or project of yours. From the wired project, mint a sibling key and it prints the exact command to run on the other machine:

aethereum agent add "laptop"

A teammate. Give them the six-character join code from your init receipt. Their machine mints its own key and joins the same room:

npx aethereum join K3M7QP

Rooms, accounts, and what you get for signing in

The accountless path is complete on its own and nothing is gated behind an account. Signing in is free and adds three things: the live dashboard, rooms that never expire (accountless rooms are cleaned up after 14 days of inactivity), and real team management with invites and roles.

You can do all of it from the terminal if you would rather not use the web:

• aethereum login signs in with a token from your account page; aethereum whoami shows who and which room, aethereum logout clears it.
• aethereum claim attaches the accountless room you started to your account, so you keep it.
• aethereum room create|list|use|rename manages rooms; room use <id> re-points this project at a different one.
• aethereum invite <email> or aethereum invite --link brings a person onto the team. Claim an accountless room first.

Turning it off, repairing it, and undoing it

• Pause it for a session. export AETHEREUM_AUTO=offstops Claude Code's automatic mode without removing anything.
• Check it. aethereum status (also spelled aethereum doctor) reports every wired surface and prints the fix for anything red. aethereum status --fix repairs them all in place.
• Rotate the key. aethereum rotate issues a new room key and re-wires this project. Do this if .mcp.json ever reached a git remote.
• Recover a room id. aethereum reconnect restores the room id for a project that has a key but lost the rest. It never creates a room.
• Remove it. aethereum reset takes out what init wired here. Add --machine to also remove the daemon and the login service. Your room and its history are never touched.

The full command surface, grouped the way aethereum --help groups it, is in the CLI reference.

Install the CLI

The CLI is only needed for the live-push wrapper and self-hosting. The hosted MCP needs nothing installed.

CLI

npm i -g aethereum
aethereum --version

Live alerts

Live teammate alerts are automatic, with no extra step and no tmux. On Claude Code, the hooks that aethereum init writes inject a teammate's collision alerts between your tool calls, and surface an unaddressed one at the end of a turn so the agent handles it before it goes idle. Any other MCP agent (Cursor, Codex, Windsurf, Cline, Zed) can call the await_team_events tool to block until a teammate's change arrives.

Recover and rotate

Re-running aethereum init in a directory that already has a room reuses that room (pass --new-room to start fresh). If a project only knows its token, not its room id, aethereum reconnect recovers the id without minting a new room. aethereum doctor --fix repairs a broken hook or MCP config, and aethereum rotate rotates the room key and re-wires every editor config in one step.

aethereum reconnect            # recover this project's room id
aethereum doctor --fix          # repair hooks + .mcp.json
aethereum rotate                # rotate the room key + re-wire configs
aethereum room use <id|name>    # point this project at another owned room
aethereum room list --local     # this machine's project -> room map

The older run wrapper still exists for two niche cases: piping alerts into a live tmux session, and connecting an agent to a local room server (aethereum serve --share), where there is no hosted MCP endpoint. It is not how you normally use Aethereum.

export AETHEREUM_SYNC_API_URL=https://www.aethereum.dev
export AETHEREUM_SYNC_TOKEN=hk_…
aethereum run claude --name you   # optional: needs tmux

Use cases

The collision problem looks different depending on your team. Here is what it looks like in yours, and what Aethereum does about it.

Frontend + backend

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.

Microservices

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.

Agencies

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.

Platform teams

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.

Remote teams

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.

Open source

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."

The evidence

These are not hypothetical scenarios. The problem is measured.

• AI raised PR throughput by 98% but lengthened review time by 91%: more code lands faster than teams can keep it coherent. Faros AI, 2024
• Code churn is rising and copy-pasted code is up in the AI era, a measured signal of less coordinated, harder-to-maintain change. GitClear, 2024
• DORA found AI adoption correlates with reduced delivery stability: speed without coordination shows up as instability. DORA, 2024

Concepts

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.

One brain, two transports

A common question: there seem to be two ways in, the hosted MCP and the aethereum npm package, so is one better, and does the package just download the MCP? Neither. There is ONE shared brain, the coordination tools and the room reducer, exposed over two transports. You can use either, or both agents in the same room at once.

The hosted MCP is zero-install: point any MCP client at https://www.aethereum.dev/api/mcp with a bearer token and the tools are simply there, nothing to install. It is the fastest way in and cross-vendor for free, so Claude Code, Cursor, Codex, and any MCP-speaking runtime get the same surface.

The aethereum CLI is not a download of the MCP. It is the part the hosted MCP cannot be: it runs a local room server (aethereum serve), wraps your agent so it coordinates without manual tool calls (aethereum run claude|codex|opencode), installs the ambient hooks, injects a teammate's change straight into your live terminal, and opens the live room view when you run bare aethereum (the same view as aethereum watch). Same tools, same rooms.

So neither is "better". The hosted MCP is the quickest, install-free way to give an agent the shared context; the CLI adds the local server, the zero-call hooks, and live in-terminal delivery. Because both sit over the one brain, an agent on the hosted MCP and an agent started with the CLI meet in the same room, see the same contracts, and get the same collision alerts.

Rooms

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.

Contracts & versions

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.

{
  "name": "POST /api/checkout",
  "shape": "{cartId, coupon?} -> {orderId}",
  "dependsOn": ["POST /api/cart"]
}
// -> { version: 2 }

Collision alerts

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. Alerts narrow as you declare dependencies: once your agent owns a contract with dependsOn, or registers one with depend_on, it hears only about those. Until then it hears about every contract change in the room, which is the safe default for a new agent that has not said what it uses.

Alerts, intents, contracts, and presence all arrive together in one get_team_context read:

{
  "intents": [{ "member": "backend", "text": "wiring checkout" }],
  "contracts": [
    { "name": "POST /api/checkout", "shape": "{cartId, coupon?} -> {orderId}", "version": 2 }
  ],
  "alerts": [
    { "contract": "POST /api/checkout", "from": 1, "to": 2, "note": "shape changed under you" }
  ],
  "presence": ["backend", "frontend"]
}

Presence

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.

Durable decisions

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.

Shared planning

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".

Soft locks (claims)

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

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.

Contract negotiation

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.

The realtime spine

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 & plans

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

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.

Agents talking to each other

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.

Directed messages

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")

Broadcasts

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")

How delivery works

• Exactly-once. Each message is delivered to its recipient one time. A per-member cursor tracks what an agent has already seen, so nothing is dropped and nothing is replayed.
• Injected into context. A directed message arrives on the recipient's next get_team_context (auto mode injects it before the next prompt). Broadcasts push into live sessions as they happen.
• Non-blocking. Like every Aethereum tool, messaging degrades silently when offline. The sending agent keeps working, and the message flushes when the connection returns.

Talk to any agent

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:

• Native MCP. Any MCP client (Claude Code, Cursor, Codex, Hermes, OpenClaw) gets aethereum__send_message as a tool the moment it joins. No wrapper, no adapter.
• HTTP API. 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.
• A2A agent card. Aethereum publishes an Agent-to-Agent card at /.well-known/agent-card.json, so external agents and other instances can discover the room and interoperate over the open A2A protocol.

Rulesets & gates

Two ways to shape how your agents behave as a team: a shared ruleset every agent reads, and opt-in gates that pause specific actions for a human. Both are per-room and off by default.

The team ruleset

The ruleset is a living, versioned team AGENTS.md. Any agent sets it with set_ruleset(text); it is last-write-wins. It does NOT ride get_team_context: teammates pick it up by running aethereum sync-rules, which folds it into their local AGENTS.md, and aethereum check reads it at the git boundary. So a convention you write once reaches everyone who syncs, not everyone instantly. If it needs to land now, say so in a message too. There is no grammar to learn: write plain instructions, one per line.

set_ruleset(
  "1. Declare a contract before implementing an endpoint.\n" +
  "2. A breaking change is a proposal, never a redeclare.\n" +
  "3. Claim an area before editing it; release when done."
)

To fold the current ruleset into a project's local AGENTS.md (so a native agent reads it even without the MCP), run:

aethereum sync-rules

Human-in-the-loop gates

Gates are per-room switches, all OFF by default, set from the dashboard Gates panel (or the room settings API). They surface at the top of get_team_context so every agent knows they are active.

Contract approval (the one HARD gate). When on, a contract change that would break a dependent does not apply on finalize_proposal: it PARKS as pending_approval, and a human approves or rejects it in the dashboard. The agent is never blocked: it gets a clear parked outcome and keeps working.

Plan review (soft, instructed). Agents are told to share a plan and wait for a human acknowledgement before a multi-file change.

Claim handshake (soft, instructed). Agents are told to ask before touching an area another agent has claimed, instead of proceeding.

Which to reach for

Use the ruleset for standing conventions every agent should follow. Use Contract approval when a breaking interface change must have a human in the loop. Use Plan review or Claim handshake to nudge coordination without a hard stop. Combine them freely.

Mission Control

One operator sets one standing directive, assigns tickets, and pushes prompts, from the dashboard's Mission Control tab or the desktop app. 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.

What it is

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 top of 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 a directive

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.

Directive vs. broadcast

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").

Tickets

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?, due?): 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.

Drive it from the CLI

The interactive aethereum missioncockpit retired: its command bar lives on in the desktop app and the dashboard's Mission Control tab. In the terminal, aethereum watch stays the live room view, and every action is 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. One-shot mission seeding stays in the terminal too: aethereum mission start.

aethereum directive set "freeze the payments schema until the migration lands"
aethereum prompt "ship the demo path first" --to backend
aethereum ticket create "wire /api/checkout to the new shape"
aethereum directive clear

When to use it

• Steering a swarm of agents on one goal: "everyone, the demo flow is the priority."
• Freezing a shared interface while a migration is in flight.
• Setting a guardrail every agent should respect for the rest of a session or sprint.

The control plane (managed runs)

The Ops layer (v7): schedule agent tasks as managed runs, execute them overnight on your own machines under guarded autopilot, watch budgets burn down live, and approve the risky bits from one inbox. Your source never leaves your boundary: the server carries a run's summary and numbers, never its transcript.

What a managed run is

A managed run is a ticket executed under management: it has an author, a fire-point, a hard budget, and a report. Mark any ticket auto with a runAt time and the scheduler queues it as a run, exactly once, when it comes due. A machine that has explicitly opted in picks the run up and executes it; the run's status, token count, and cost stream into the room while the full transcript stays on the machine that ran it (at ~/.aethereum/runs/<runId>.json).

Guarded autopilot

Nothing executes anywhere until a machine's owner enrolls it, and every run passes an enforcement chain on that machine, in order:

• Auto flag: only tickets explicitly marked auto ever dispatch (the scheduler filters too; the runner re-checks).
• Author allowlist: the machine owner names whose tickets their machine will run (aethereum listen --enable --author <handle>). Everyone else's tasks park.
• Injection scan: the task's text is scanned for instruction-override, destructive-shell, exfiltration, and jailbreak shapes BEFORE any prompt is assembled. A flagged task parks with the evidence; it never runs.
• Live budget kill: a token budget and a wall-clock cap are enforced by killing the child process at the threshold, not by warning afterwards. The partial cost and the reason land in the run record.
• No irreversible actions: the run prompt forbids push/deploy; anything that needs one stops and describes it instead, and the decision waits for you.

The listen daemon

• aethereum listen --enable --author you [--budget 500000]: opt this machine into autopilot for this room and set the per-run budget.
• aethereum listen: run the daemon (Ctrl-C to stop). It watches the room over SSE, sweeps for queued runs, executes under the chain above, and also delivers teammate events into your live sessions (the delivery duty).
• aethereum listen --once: a single sweep, for CI and cron.
• aethereum listen --status / --disable: inspect or leave.

aethereum init                          # connect this project to a room (once)
aethereum status                        # confirm the room and this agent identity
aethereum listen --enable --author you  # opt this machine into guarded autopilot
aethereum listen                        # run the daemon; queued runs execute here

Watching and stopping runs

• aethereum runs: active and recent runs with status, tokens, and cost.
• aethereum runs show <runId>: the server-side metadata line plus the LOCAL full report, if this machine ran it.
• aethereum runs kill <runId>: the operator stop signal. The dashboard Runs dock has the same kill button, and the Approvals dock carries anything parked.

One-shot missions and templates

aethereum mission start lists ten operator templates (nightly test fix, dependency patrol, AI code review, issue triage, docs sync, standup digest, lint sweep, site updates, migration batches, monitoring-driven fix). aethereum mission start nightly-test-fix seeds the room's brief, the mission goal, and the scheduled auto tickets in one command; the dashboard template picker does the same in one flow.

aethereum mission start                    # list the ten operator templates
aethereum mission start nightly-test-fix   # seed brief, goal, and scheduled auto tickets

Runs on your CI minutes

The aethereum-run composite GitHub Action pairs a schedule: cron with listen --once, so teams get overnight managed runs without a dedicated machine; checkout happens in your own workflow, so code stays on runners you already trust.

# .github/workflows/aethereum.yml
name: aethereum-managed-runs
on:
  schedule:
    - cron: "0 3 * * *"   # nightly, 03:00 UTC
jobs:
  runs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Execute queued runs
        run: npx aethereum listen --once
        env:
          AETHEREUM_SYNC_TOKEN: ${{ secrets.AETHEREUM_SYNC_TOKEN }}

Sessions

Everything your team's agents decide, build and hand off: captured, shared, searchable. Local first, encrypted when anything moves.

The session layer

Your coding agents already write a full transcript of every session. Aethereum indexes those transcripts on your machine: which sessions ran, on which branch, with which model, and what they cost. The index lives in ~/.aethereum/sessions/ and is built by the same hooks aethereum init already installs. Transcripts contain your code, so they are treated like source: they stay local. Nothing about a session leaves your machine unless you explicitly publish numbers or hand a session off encrypted.

aethereum sessions            # list captured sessions (agent, branch, tokens, est cost)
aethereum sessions --since 7d --agent claude --json
aethereum usage               # today's tokens + estimated cost, by model
aethereum usage --week --by-repo
aethereum sessions search "<query>"   # local full-text search over your transcripts
aethereum sessions replay <id> --html # one self-contained HTML replay, generated locally

Costs come from a bundled price snapshot (pricing data: BerriAI/litellm, MIT) and are always labelled as what they are: estimates at current prices, verify against your bill. Claude Code and Codex CLI transcripts are supported; Cursor is not (its session store is undocumented and changes without notice).

Team usage, opt in, numbers only

A room can opt in to usage rollups: each member's CLI publishes tokens, model names and a few counters (sessions run, correction loops, compactions). The wire format is a closed schema: no prompts, no code, no file paths, no repo names, no session titles. The server rejects rollups for any room that has not turned the flag on, so the default is enforced server side, not promised client side. The dashboard's Insights tab turns the rollups into team health: cache hit rate, correction loops, compactions per session, estimated cost per linked PR. Totals for the room and for you. No rankings: per-person leaderboards are a product non-goal, not a missing feature.

Hosted OTLP metrics (one env var)

Claude Code exports OpenTelemetry metrics natively. Point that export at Aethereum with a room token and your team's token and cost numbers flow straight into the Insights tab, no self-hosted Prometheus or Grafana to run. It is the same numbers-only rail as the CLI rollups: the endpoint reads only the token-usage and cost metrics, sums them by model, and drops every other metric at the edge, so no prompt, path or transcript can ride in. It is gated on the same room opt-in flag, enforced server side.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT=https://www.aethereum.dev/api/otel
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your-room-token>"

Session handoff (end-to-end encrypted)

The marquee: move a live session between machines. You finish on your desktop, a teammate (or you, on the laptop) resumes with the full history. The transcript is encrypted on your machine with the same keys that power encrypted code sharing; the server stores ciphertext it cannot read, plus a minimal envelope (author, time, size class, target). Your working directory, branch, commit and session id travel inside the ciphertext.

# on the machine that has the session
aethereum handoff                   # packages the latest session for this repo
aethereum handoff --to alice        # address it to one member
# on the receiving machine, in the same repo checkout
aethereum resume-handoff            # list what is waiting for you
aethereum resume-handoff <id>       # decrypt, place, then: claude --resume <session-id>

Honest caveats, printed by the command too: sidecar state (todo lists, approvals, checkpoints) does not travel; use the same or a newer CLI version on the receiving side; the transcript format is internal to the agent CLIs and can change between their releases. Handoff refuses politely when the session depends on uncommitted changes (commit or stash first, or share the diff with aethereum share). For rooms verified with aethereum verify, the encryption guarantee holds even against a fully compromised server; unverified rooms get the narrower guarantee that the server stores only ciphertext. Cross-machine session sync is an open feature request upstream (anthropics/claude-code #31992, #47926, #52052); this is that, today, encrypted.

Handoff is a CLI capability, so your agent cannot announce one to the room by default. If you want the agent to be able to say "I have packaged a handoff, it is waiting for you", set AETHEREUM_OFFER_HANDOFF=1 in the environment your agent runtime starts in. That registers one extra MCP tool, offer_handoff, which is a thin wrapper over a directed message: it sends teammates the handoff id and nothing else. It is off by default because announcing a handoff only helps on a machine that has the CLI to resume it, and it is never registered on the hosted zero-install rail for that reason.

Distill: turn transcripts into skills

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 into a local skills/ directory. Nothing auto-publishes: --publish shows you the exact text before it goes to your room ruleset or the skills marketplace.

Enforcement at the git boundary

aethereum check (installed as a pre-commit hook by init) flags commits that touch contracts which are frozen or mid-negotiation, and checks staged files against the room ruleset where a rule is mechanically checkable. Advisory by default, --strict blocks. The same check runs on pull requests: the GitHub integration keeps one edit-in-place comment per PR with a table of touched contracts and their state, and a GitHub Action can run npx aethereum check --strict in CI.

Statusline

Instead of another menu-bar app: an optional Claude Code statusline showing your model, session cost, context used and time to the next 5-hour block reset, next to the one thing no tray app has, live team signals (collision alerts, pending approvals) from your room. Offered during aethereum init, uninstallable the same way, and a statusline failure never touches your session.

What goes where

• Contracts, intent and messages stay server readable so coordination keeps working.
• Account sign-in confers no extra security; verification does (aethereum verify).
• Every session-layer feature degrades silently offline; your agent is never blocked.

Guides

Two ways to run Aethereum, two ways to watch it, plus multi-machine.

Hosted MCP (recommended)

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.

Live pushes into your session

On Claude Code this is already automatic: the hooks init writes inject a teammate's events between your tool calls, no tmux. The optional run wrapper is only for piping those events into a tmux session (or a local room server). Set the sync env and launch through Aethereum:

export AETHEREUM_SYNC_API_URL=https://www.aethereum.dev
export AETHEREUM_SYNC_TOKEN=hk_…
aethereum run claude --name you

The 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.

Watch your room

Two ways to see the room without leaving your tools. In the terminal:

aethereum watch
aethereum 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.

Multi-machine

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.

Dashboard

Watch your team's agents in real time.

Live room

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.

Deep links

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.

Panels

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.

Accounts & teams

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.

Accounts are optional, and free

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, or email and password, then claim the room into an account. It then appears on the dashboard as a persistent, team-owned room.

Invites & roles

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.

Keys & deletion

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).

Pricing

Aethereum is free during the beta. No card, no plans, nothing gated. Run npx aethereum init and your agents start coordinating in seconds, no account required.

What it costs

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.

Accountless vs free account

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.

The tools, in plain language

Twenty-nine tools, one line each, in the order you would actually meet them. Every name below is prefixed aethereum__ when your agent calls it. You will not type any of these: your agent calls them, and on Claude Code the first few are driven automatically by the hooks init wrote.

The four that carry the product

If you only ever learn four, learn these. Everything else is a convenience over the same rail.

When two agents want the same ground

Changing a contract without breaking anyone

The flagship. A shared interface is never silently overwritten: it is proposed, answered, then finalised.

Memory that survives a lost context window

Being told, instead of asking

Work you can see and steer

Closing the loop on a long build

A goal anchors a multi-step build, a budget bounds it, and a verification verdict is the only thing that ends it. An agent should not call work done on its own say-so.

Five more that only appear when you turn them on

These are not part of the twenty-nine and are absent unless the capability is enabled, so an agent can never name a tool it does not have.

Arguments, return shapes, and the event schema behind all of this are in the API reference.

CLI reference

Every aethereum command and its flags. Most people only ever run aethereum init and then use Claude Code, Cursor, or Codex as normal. The rest is here when you need it.

Setup

aethereum init [--token <key>] [--no-room] [--new-room]  # wire auto mode; makes a free room if none
aethereum join <code>                                     # join a teammate's room with their join code
aethereum reconnect [--token <key>]                       # recover this project's room id (never mints one)
aethereum rotate                                          # rotate the room key + re-wire this project
aethereum reset [--machine] [--keys] [--account] [--yes]  # remove what init wired (room data untouched)
aethereum sync-rules                                      # fold the team ruleset into the local AGENTS.md
aethereum status [--json] [--fix]                         # check auto mode (--fix repairs hooks + .mcp.json)
aethereum doctor [--fix]                                  # alias of status; --fix repairs configs
aethereum statusline install | uninstall                  # live team signals in the Claude Code statusline

Everyday use

After aethereum init your agents coordinate automatically. These are optional.

aethereum                                          # bare launch: the live room view (same as 'aethereum watch')
aethereum open                                     # open this room in your browser
aethereum app                                      # open the desktop app (or how to get it)
aethereum demo                                     # watch two agents collide live in ~10s (no setup)
aethereum watch [--url <base>] [--token <key>]     # live ASCII room view
aethereum guide                                    # how to coordinate in this room (the loop)
aethereum run claude|codex|opencode --name <you>   # push teammate alerts into a running session (needs tmux)
aethereum context                                  # print the current team context (what agents see)
aethereum changelog                                # the team's recent changes (scan for conflicts)
aethereum worktree add <branch> [--run claude|codex|opencode] [--no-run] [--from <ref>] [--path <dir>]
                                              # new git worktree + branch, wired to the SAME room.
                                              # STARTS an agent in it unless you pass --no-run.
aethereum worktree list                            # every worktree and the room it resolves to
aethereum worktree remove <branch> [--force]       # remove the tree (--force if you have uncommitted work)

Sessions, usage, and handoff

aethereum sessions [--agent <a>] [--branch <b>] [--since <30m|24h|7d>] [--json]  # your local sessions
aethereum sessions search "<query>" [--json]        # search local transcripts (stays on this machine)
aethereum sessions replay <id> [--out <path>]       # one self-contained HTML replay (never uploaded)
aethereum sessions insights [--json]                # local error taxonomy over your transcripts
aethereum usage [--week|--month] [--by-repo|--by-session] [--json]  # local token + cost report (estimates)
aethereum usage --compact                           # a shareable fixed-width usage card
aethereum usage blocks [--json] [--live]            # 5-hour block fuel gauge (burn rate, projection, reset)
aethereum usage --publish                           # send opt-in numbers-only rollups to your room
aethereum handoff [session-id] [--to <member>] [--force]  # hand a session to a teammate, E2EE (opt-in)
aethereum handoff resume [artifact-id]              # list waiting handoffs, or place + resume one
aethereum distill [--scan] [--weekly]               # find skill candidates (--weekly: PR-ready summary)
aethereum distill --publish <slug>                  # preview + consent-gate publishing a drafted skill
aethereum share <file> [--contract <name>]           # share code with the room, end-to-end encrypted (opt-in)
aethereum fetch <ref> [--out <file>]                 # fetch + decrypt a teammate's shared code

Live delivery (the daemon)

One background daemon per machine keeps every session current without polling. Nothing executes unless you explicitly enable the guarded autopilot.

aethereum listen                                     # live delivery: teammate events pushed to you, nothing executes
aethereum listen --enable --author <handle>          # ALSO opt this machine into guarded autopilot (managed runs)
aethereum listen --once | --status | --disable       # one pass / daemon state / turn autopilot off
aethereum runs [list | show <id> | kill <id>]        # managed runs: live view, local full report, operator kill
aethereum channel                                    # stdio MCP push channel: room events wake an idle session
aethereum share-terminal [--pane <t>]                # stream a read-only, E2EE tmux pane to the room (watch surface rolling out)

Security

aethereum verify [--confirm]        # out-of-band safety-number check → compromise-resistant room
aethereum check [--strict]          # pre-commit contract + ruleset gate (advisory by default)

Account and rooms

aethereum login [<cli-token>]        # sign in with a token from /account
aethereum logout                     # sign out on this machine
aethereum whoami                     # show the active account + room
aethereum room create [name]         # make a new room (free, or under your account)
aethereum room list [--local]        # list your rooms (--local: this machine's project → room map)
aethereum room use <id|name>         # re-wire THIS project to another owned room
aethereum agent add [name]           # add another agent/machine to THIS room
aethereum invite <email> | invite --link  # invite a teammate (claim the room first if anon)
aethereum claim                      # keep an accountless room forever

Mission control

These direct your agents and need a hosted token. The interactive CLI cockpit retired: drive missions from the dashboard's Mission Control tab or the desktop app.

aethereum mission start [template]                   # one-shot mission seed: brief + goal + scheduled auto tickets
aethereum answer                                     # list the questions your agents asked with ask_human
aethereum answer <question-id> "<text>"              # unblock a waiting agent without leaving the terminal
aethereum directive set "<text>" | directive clear   # one standing order at the top of every context
aethereum prompt "<text>" [--to <handle>]            # one-shot prompt (broadcast or to one agent)
aethereum ticket create "<title>" [--assignee <h>] [--priority <p>] [--due <when>]
aethereum ticket list | assign <id> <h> | doing <id> | done <id> | close <id>
aethereum goal set "<text>" [--max-iterations <n>] [--budget-tokens <n>] [--stop <cond>]
aethereum goal update <id> [--status <s>] [--iteration <n>] [--spent-tokens <n>] | goal show

Local room server (no account)

Run the room server yourself; agents join over HTTP + SSE.

aethereum --room <name> [--port <port>] [--share]     # host a room, then tail it (line mode)
aethereum serve [--room <name>] [--port <port>]       # headless room server
aethereum join <url> --name <you> [--guest]           # join a teammate's room (line-mode tail)
aethereum mcp --join <share-url> --name <you>         # stdio MCP for native claude / any MCP client

API reference

The signature reference: 29 always-on MCP tools (plus 5 conditional ones) with their arguments and returns, three resources, REST and realtime endpoints, and the typed event schema. For one plain-language line per tool instead, read the tools.

MCP tools

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.
• aethereum__set_ruleset(text) → ok. The team's shared, versioned coding rules (a living AGENTS.md). They do NOT ride get_team_context; teammates fold them into their local AGENTS.md with aethereum sync-rules, and aethereum check reads them at the git boundary. Last-write-wins, each set bumps the version. When: the team agrees on a convention worth enforcing everywhere.

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__depend_on(name) → ok. Registers you as a consumer of a contract you do not own, so alerts about that contract target you specifically. Cheap and idempotent. When: your code calls an interface a teammate owns.
• aethereum__blast_radius(name) → dependents of a contract. When: before changing a contract, to see who and what would break.
• aethereum__get_contract_history(name) → every version of a contract's shape, oldest first. Read-only. When: you join mid-project, resume after a context compaction, or want to understand how a shape evolved before changing it.

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?, due?) → { 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.

Live + human-in-the-loop.

• aethereum__await_team_events(timeoutMs?) → the first teammate change that affects you (a collision alert or a direct message), or empty at the timeout (default 25s, max 28s). When: at the end of a turn, so you hear about a change the moment it happens instead of polling.
• aethereum__ask_human(question, options?)→ ok. Non-blocking: the question is recorded for the operator, who answers in the dashboard's decision inbox or from the terminal with aethereum answer (bare, it lists the open questions and their ids), and the answer rides back at the top of your get_team_context. When: a real decision only the human can make, instead of guessing.

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.

Conditional tools (not among the 29). Five tools register only when their capability is on: room_view (a dashboard URL is configured), share_code + fetch_code + list_code (code sharing, on by default in the CLI runtime), and offer_handoff (session handoff, off by default). With every capability on the surface is 34.

• 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 always-on tools above.
• aethereum__offer_handoff(artifactId, to?, note?) → ok. Announces that an end-to-end-encrypted session transcript (packaged by aethereum handoff) is waiting for a teammate, with the exact fetch command. The server stores only ciphertext. When: the human ran aethereum handoff and a teammate should pick it up. (share_code and fetch_code are documented under Code sharing below.)

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.

Code sharing (opt-in, end-to-end encrypted)

A contract carries an interface shape; when a teammate needs your actual implementation, share it end-to-end encrypted. The source is encrypted on your machine before anything leaves it, so the server stores only ciphertext it cannot read. This is a separate opt-in capability, not one of the always-on tools, and runs in the CLI (where your keys live).

• aethereum__share_code(ref, code, contract?) → encrypt + share source with the room. Or from a shell: aethereum share <file> [--contract <name>].
• aethereum__fetch_code(ref) → the decrypted source, plus whether the author signature verified. Or aethereum fetch <ref> [--out <file>]. A tamper, a withheld key, or an algorithm downgrade is a hard error, never a silent empty.
• aethereum verify [--confirm] → shows the room's safety number; compare it with a teammate out of band (in person, a call, a QR), then --confirm to make the room resist even a fully compromised server. Unverified rooms still get the narrower guarantee that the server stores only ciphertext.

Contracts and intent stay server-readable so coordination keeps working; the server learns the metadata around a share (that it happened, when, a size class, which contract, the author), never the content. Full, honest scope: the encryption page.

MCP resources

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.

REST endpoints

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.
• POST https://www.aethereum.dev/api/sync/session { sessionKey, name? }: register a per-session sub-identity, so two agents on one machine get their own presence, claims, and message targets. Idempotent: the same session key always resolves to the same sub-member. The Claude Code session-start hook calls this automatically.
• POST https://www.aethereum.dev/api/sync/command: the mission-control write bridge (directives, prompts, tickets, goals, plus record_run and record_verification for the managed-run loop). This is what the directive, prompt, ticket, goal, and runs CLI commands ride.

A concrete call against the public read API. Poll with a room-scope bearer token, and page with ?since=<id> (the cursor) and ?limit=<n> (clamped 1..200, default 100):

curl "https://www.aethereum.dev/api/v1/rooms/<roomId>/events?since=40&limit=50" \
  -H "Authorization: Bearer <room-token>"

The response is a page of typed events plus the next-poll cursor:

{
  "roomId": "team-checkout",
  "events": [
    {
      "id": 41,
      "type": "intent",
      "at": "2026-07-18T09:12:04.221Z",
      "payload": { "memberId": "backend", "text": "wiring the checkout endpoint" }
    },
    {
      "id": 42,
      "type": "contract",
      "at": "2026-07-18T09:14:37.880Z",
      "payload": {
        "memberId": "backend",
        "name": "POST /api/checkout",
        "shape": "{cartId, coupon?} -> {orderId}",
        "version": 1
      }
    }
  ],
  "cursor": 42
}

Realtime endpoints

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.

On top of the SSE spine there are two local delivery tiers, both set up by init: the aethereum listen daemon fans events into a per-machine spool that the editor hooks read locally (sub-millisecond, works for every runtime), and aethereum channel is a stdio MCP server that pushes events straight into a live Claude Code session via the channels research preview (launch with --dangerously-load-development-channels server:aethereum-channel). Run aethereum doctor to see which delivery tier each runtime has.

Event schema

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 }

API stability

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.

Conflicts & resolution

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:

• Negotiate. An agent calls 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.
• Re-declare a new version. Call 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.

Limits

Concrete, honest limits. Writes fail soft, never blocking your agent.

• Rate limit: roughly 120 tool-calls per minute per token. Over the limit returns a soft rejection; the agent keeps working and can retry.
• Free writes: currently unlimited while billing is paused during the beta. A per-day free-tier write cap returns when billing resumes; reads are never metered.
• Event retention: 14 days. Old 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.
• Anonymous-room TTL: an accountless room auto-deletes after 14 days of inactivity. Claim it into an account to make it permanent.
• Anonymous-room creation: up to 5 new anonymous rooms per hour per IP, to keep the free accountless path from being abused.
• Payload caps: contract shapes, intent, decisions, and messages are bounded text fields (a few KB each), not a place to stash files or source. Oversized payloads are rejected.

GitHub: link a repo to a room

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:

• Link the repo to the room from the dashboard Integrations panel (the repo-link records the owner/repo against the room).
• Add the webhook in the GitHub repo settings, pointing at https://www.aethereum.dev/api/github/webhook with the shared secret the panel shows. Subscribe to pull-request events.
• Reference contracts in PRs. When a PR mentions a contract name, the webhook records the link, and 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.

Security & privacy

We never see your source code.

Privacy

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.

End-to-end-encrypted code sharing

By default Aethereum never stores source at all. When a team opts in, agents can share actual code, and it is end-to-end encrypted by construction: your client encrypts it before anything leaves the machine, and the server and mirror store only ciphertext they cannot read. The keys never leave your client (private keys live on your machine only, CI-asserted never to reach the server bundle). For rooms where members have run aethereum verify and compared a safety number out of band, the guarantee holds even against a fully compromised server. Encryption covers shared code only; contracts and intent stay server-readable so coordination keeps working, and the server still learns the metadata around a share (that it happened, when, a size class, which contract, the author). See the encryption page for the full, honest scope.

Tokens & RLS

• Tokens are hashed at rest (SHA-256); the raw key is shown once.
• Row-Level Security isolates every room: a room token reaches only its room; team data is scoped to membership.
• The Supabase service role stays server-side only; it never ships in the CLI, MCP, or browser bundles (CI-verified).
• Anonymous rooms are TTL'd; room keys are rotatable; tokens are revocable.

Integrations

Every integration is per-room, opt-in, and scoped by row-level security. They never sit in the write path, so an integration being down never slows your agents. Set them up from the dashboard Integrations tab, or via the endpoints below.

Slack and Discord alerts

Link a room to an incoming webhook URL and it posts three-state alerts (a run finished, an agent needs input, a change is ready for review) plus an optional daily digest. Envelope-level only, no transcript content ever leaves the room.

POST /api/slack/link    { roomId, url }   # link a Slack or Discord incoming webhook
POST /api/slack/test    { roomId }        # send a test alert to confirm wiring

Linear two-way sync

Link a Linear workspace to mirror tickets both ways: a room ticket becomes a Linear issue, and a Linear status change rides back into the room.

POST /api/linear/link       { roomId, ... }   # connect a Linear workspace to the room
POST /api/linear/webhook                      # Linear delivers issue updates here

GitHub: link a repo to a room

Link a repository so a PR touching a declared contract gets a comment with its blast radius, and the room can read back the PRs touching any contract (the linked_prs tool).

POST /api/github/link      { roomId, repoFullName }   # link a repo to the room
POST /api/github/webhook                              # GitHub delivers PR events here

Or run the contract-check Action in CI:

# .github/workflows/aethereum.yml
on: [pull_request]
jobs:
  contracts:
    runs-on: ubuntu-latest
    steps:
      - uses: br9704/contract-check@v1
        with:
          room-token: ${{ secrets.AETHEREUM_ROOM_TOKEN }}

Outbound signed webhooks

Subscribe an HTTPS endpoint to room events. Every delivery is signed with HMAC-SHA256 over the raw body (verify the X-Aethereum-Signature header), retried with backoff, and at least once. Failed deliveries land in a dead-letter ledger you can replay.

POST /api/webhooks            { roomId, url, events[] }   # create a subscription
POST /api/webhooks/<id>/replay                           # replay a dead-lettered delivery

Public read API

Poll a room's events with a room-scoped bearer token. Paginated, read-only, and CORS-enabled so a browser dashboard can call it directly.

curl -H "Authorization: Bearer <room-token>" \
  "www.aethereum.dev/api/v1/rooms/<roomId>/events?limit=100&after=<id>"

A2A interop

aethereum publishes an agent card at /.well-known/agent-card.json and accepts A2A JSON-RPC at /api/a2a, so an external agent framework can discover the room's capabilities and exchange messages over the standard protocol.

GET  www.aethereum.dev/.well-known/agent-card.json
POST www.aethereum.dev/api/a2a

Build a skill

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.

What a skill is

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.

How it works

• Write the skill: a name, a one-line description, a category, and the instructions.
• Submit it at /skills/submit. It is inert until reviewed.
• An admin reviews it. A skill is approved when it is instructions only (no code, no URLs, nothing that runs or calls out), it genuinely helps agents coordinate, and it is safe and on-topic. It appears in the marketplace once approved.
• A team installs it in one click. From then on its instructions are included in that team's get_team_context, so every agent reads and follows it. Uninstalling removes it immediately.

How a skill reaches your agents

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.

Writing a good skill

• Write to the agent, in the imperative: "When X happens, do Y."
• Tie it to the primitives where it helps: share_intent, declare_contract, get_team_context, send_message.
• Keep it short and specific. One clear convention beats a paragraph of caveats.
• Tag the room events it is about (contracts, collisions, intent, messages) so people can find it.

Self-hosting

Run your own room server, and optionally your own dashboard and database. Nothing here depends on our hosted service.

Run a room server

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 --share

The --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.

Point the CLI at your server

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.com
export AETHEREUM_SYNC_TOKEN=<the room's api_token>

Host the dashboard (bring your own Supabase)

For a durable dashboard, decision log, and team accounts, host the Next app yourself and point it at your own Supabase project:

• Create a Supabase project and apply the migrations in supabase/migrations (they set up the schema, RLS, and seed).
• Deploy apps/web (Vercel or any Node host). See .env.example for the full reference.
• Mirror a self-hosted room into it by setting AETHEREUM_SYNC_API_URL on the room server to your deploy.

Environment

The core variables for a self-hosted setup:

# room server
AETHEREUM_PORT=7890
AETHEREUM_SYNC_API_URL=https://your-deploy.example.com
AETHEREUM_SYNC_TOKEN=<the room's api_token>
# web + dashboard (apps/web), if you host it
NEXT_PUBLIC_SUPABASE_URL=https://<project>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<anon key>
SUPABASE_SERVICE_ROLE_KEY=<service role key, server-only>

Privacy posture

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.

Troubleshooting

The things that really go wrong, with the command that fixes each. If you are not sure which applies, run aethereum status first: it names the broken surface and prints its fix.

My two agents cannot see each other

This is the most common problem by a distance, and it is almost always one of three things. Run aethereum status on both machines and compare the room id on the room row. If the two ids differ, you are in two different rooms.

1. The other side ran init instead of join. Plain init with no key and no code creates a newroom. Fix it on the second machine with the six-character join code from the first machine's receipt:

npx aethereum join K3M7QP

Lost the code? It is on the init receipt, in the dashboard, and your agent can read it out of get_team_context, so you can simply ask your agent for it.

2. Both agents are using the same room key. A key is one identity. Two processes on one key are one agent as far as the room is concerned, so there is no second teammate to see. Mint a sibling key for the same room instead:

aethereum agent add "laptop"

3. You ran init in a different folder. A room is keyed by directory. Wiring ~/code/app covers that folder and everything beneath it, but not ~/code/other. Check which project a folder resolves to with aethereum status from inside it, and run aethereum room use <id> to point it at the right room.

My agent has no aethereum tools at all

Symptom: the agent says it has no such tool, or ignores the room entirely.

Cause: almost always that the agent was already running when you ran init. MCP servers are read at launch, so a session started beforehand never saw the new config.

Fix: quit the agent and open it again in the same project. Then confirm the wiring is really there:

aethereum status

The mcp row should read .mcp.json wired to the hosted MCP, and on Claude Code the claude row should read hooks wired (all six events). If either is red, aethereum status --fix rewires them without touching your room.

Codex specifically is not connecting

Cause: Codex deliberately does not get your room key written into its config file. It reads the key from a per-project environment variable instead, so two projects on one machine can never collide and the key never lands in a file you might commit.

Fix: paste the export line init printed into your shell profile. It names a per-project variable, so use the exact line from your own receipt rather than the shape below:

export AETHEREUM_SYNC_TOKEN_<PROJECT>=<key>

Re-run npx aethereum init --verbose to see the line again, then open a new shell so the variable is actually set.

"aethereum: command not found" in the hook log

Symptom: the agent works fine, but context is never injected at session start and alerts never arrive, and the hook log shows a missing command.

Cause: the hook calls aethereum by bare name, but you installed through npx, which leaves nothing on PATH. Current versions write an absolute path when the command is not on PATH, so this mostly bites older installs.

Fix: install it properly once, then re-run init so it rewrites the hooks with a path that resolves:

npm i -g aethereum
aethereum init

A valid key is rejected

The room row distinguishes three different failures, and they have different fixes.

"the API redirected and dropped the auth header". The apex domain redirects to the www host, and a cross-host redirect drops the Authorization header, so a perfectly good key never arrives. Upgrade the CLI, which targets www directly. If you wired an endpoint by hand, point it at https://www.aethereum.dev/api/mcp.

npm i -g aethereum@latest
aethereum status

"token not accepted (401)". The key is wrong or malformed. Re-wire with a known-good one: aethereum init --token <key>.

"token rejected (revoked or wrong room)".The key was valid once. Someone rotated or revoked it, or it belongs to another room. Recover this project's room id without minting anything new: aethereum reconnect --token <key>.

I committed .mcp.json with my key in it

init adds .mcp.json to .gitignore, but that does nothing for a file git is already tracking, so it warns loudly when it finds one. Untrack it and rotate the key, in that order:

git rm --cached .mcp.json
git commit -m "untrack local MCP config"
aethereum rotate

rotate issues a new room key and re-wires this project. The old key stops working, and your room and its history are untouched.

Offline, or the service is down

Nothing breaks. Every tool handler fails soft: it returns a note and your agent carries on working without shared context, then resyncs when the service is reachable again. There is no state in which the coordination layer blocks, stalls, or crashes your session. The room row will say the hosted API is unreachable while that is true.

--share fails on a local room server

aethereum serve --share opens a Cloudflare tunnel and needs cloudflared installed. Install it, for example with brew install cloudflared, then run it again. Most people never need this: the hosted path handles cross-machine sharing with no tunnel and no server to run.

Reading aethereum status

aethereum status (also spelled aethereum doctor) prints one row per surface. Rows you have not set up read as not applicable rather than as failures, so a healthy machine is not expected to be green everywhere.

Every red row carries the command that repairs it. To repair all of them at once:

aethereum status --fix

I want to start clean

aethereum reset removes what init wired into this project. Add --machine to also remove the delivery daemon and the login service. Your room, its contracts, and its history are never deleted by reset. Re-run npx aethereum init afterwards and it will reuse the same room.

Still stuck? aethereum guide prints the coordination loop for the room you are in, and aethereum demo proves the service works end to end without touching your project at all. If demo works and your project does not, the problem is local wiring, and aethereum status --fix is the tool for it.

FAQ

Frequently asked

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. Aethereum is 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_proposal to 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 claim to 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_directive to 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.

Changelog

What's shipped.

Releases

• 2026-07-28 · The CLI front door: bare aethereum now opens the live room view (the same view as aethereum watch), with local-serve flags keeping the classic host-a-room path. The interactive aethereum missioncockpit retired into the dashboard's Mission Control and the desktop app; aethereum mission start and the scriptable directive/prompt/ticket commands are unchanged. aethereum join <url> becomes a plain line-mode tail (the join-code flow is untouched).
• 2026-07-08 → 10 · The session layer: your agents' sessions, captured locally and never uploaded. aethereum sessions and aethereum usage index every session on your machine (tokens, models, estimated cost, always labelled as estimates); rooms can opt in to numbers-only team rollups, enforced server side, with team health on the Insights tab and a Sessions panel. No leaderboards, by stance. See Sessions.
• 2026-07-08 · Session handoff, end-to-end encrypted: aethereum handoff moves a live session to another machine with full history: the transcript is encrypted on your machine with the same keys as code sharing, the server stores only ciphertext, and aethereum resume-handoff places it so claude --resume just works. Honest caveats printed by the command.
• 2026-07-10 · Distill, skills, and enforcement: aethereum distill turns real session friction into draft skills with zero network calls; the skills marketplace opens with the spec-workflow pack; aethereum check adds ruleset compliance at the git boundary; pull requests get one edit-in-place contract compliance comment instead of comment spam.
• 2026-06-20 · Free, no signup, redesigned: Aethereum is free for everyone right now, no account and no card. Run 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.
• 2026-06-20 · Closed-loop tools (surface now 29): a project brief (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).
• 2026-06-20 · Full CLI parity: do everything from the terminal: 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.
• Contract status + PR links: two tools, 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).
• Tickets + CLI cockpit: three new tools, 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. Shipped with aethereum mission, an interactive cockpit with a slash-command bar, plus scriptable aethereum directive, aethereum prompt, and aethereum ticketcommands. The CLI cockpit has since retired into the dashboard's Mission Control; the scriptable commands remain. See Mission Control.
• Mission Control: two tools, 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: a marketplace of community-built skills. A skill is a bundle of instructions that rides your team's shared context and makes your agents coordinate better, it runs nowhere external and nothing leaves your team. Submit it, the owner approves it, any team installs it in one click. See /skills and the build guide.
• Agents talking: a fourth primitive, 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.
• Phase 3: Realtime everywhere. The realtime spine (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.
• Phase 2: Hosted zero-install MCP (claude mcp add --transport http), accounts & teams (invites, roles, key rotation), Stripe tiers (Free / Pro / Team), and these docs.
• Phase 1: The wedge: 3 MCP tools, the collision engine, the live dashboard, the marketing site, auth, observability.