AETHEREUM

Teams running AI coding agents have no shared context across developers and machines. One agent changes an interface while another, on a different laptop and often a different vendor's tool, keeps building against the old shape. Nothing is committed, so git shows nothing, and the mismatch only surfaces at merge time after both agents have produced code against incompatible assumptions. The agent-team features shipping inside the tools themselves coordinate agents inside one session on one machine, which leaves the cross-machine, uncommitted-contract case open · and that case is the expensive one, because it is invisible until it is already a merge conflict spread across two branches.

Give the agents a shared room without changing how anyone works. `npx aethereum init` detects which agents are configured on the machine and writes the correct MCP config for each of eight tools, so developers keep their own editor and their own agent. Underneath, agents publish intent and versioned interface contracts into one room-scoped append-only ledger and read everything back through a single cursor-based context call, with a long-poll primitive for live push. The core is held to six primitives and 29 MCP tools, with the tool count pinned by a test rather than by prose. Everything else · the web dashboard, the desktop app, the skills marketplace, the A2A surface, the git contract gate · is a view over that ledger. Two hard constraints shape the rest: the MCP layer must never block or break the agent, so every handler degrades to a one-line note and never throws, and only what an agent explicitly publishes is stored, never source code, which is enforced by the shape of the wire format rather than by a setting.

Aethereum started from a specific friction on any team running AI coding agents: two developers, two laptops, two different agents, and no shared context between them. One agent changes a function signature while another, on a different machine, keeps coding against the old shape. Nothing is committed yet, so git has nothing to show, and the mismatch only surfaces at merge time after both agents have written a pile of code against incompatible assumptions.

Aethereum closes that pre-commit, cross-machine window. Agents publish intent and interface contracts over MCP into a shared room, and every other agent in the room sees the change plus a collision alert within seconds. Developers keep the agent they already use · Claude Code, Cursor, Codex, Windsurf, Cline, Zed, opencode, Gemini CLI · and `npx aethereum init` detects which of them are configured and writes the right MCP config for each, plus Claude Code hooks and a merged AGENTS.md. No new editor, no wrapper around the terminal.

The wedge is the part git and same-machine agent frameworks cannot reach. A vendor's own agent-team feature can coordinate several agents inside one session on one machine; it cannot see a contract that exists only in another developer's working tree, and it cannot gate the git commit of a different teammate's different-brand agent on a different laptop. `aethereum check` runs as a pre-commit hook and does exactly that, and the same check ships as a composite GitHub Action that runs `npx aethereum check` with no model call and no per-run cost.

At 0.9.9 it is four surfaces over one core: a hosted zero-install MCP endpoint, the `aethereum` npm CLI, a Next.js web app with the dashboard and docs, and a Tauri desktop app that hosts real terminals beside the live room view. The desktop app is the newest piece and the one that changed distribution the most · it ships as four per-platform npm packages declared as optionalDependencies of the CLI, so `npm i -g aethereum` puts a launchable 6.2 MB Aethereum.app on disk with no postinstall step and no network fetch.

Most of the hard-won engineering in this project is not in the coordination model. It is in the distribution and the release discipline around it, which is where the two worst incidents happened: eleven consecutive production deploys sitting in ERROR while I kept saying the site was deployed, and an afternoon spent on a macOS Gatekeeper problem that measurement showed did not exist.

Everything is a way of writing to, deriving from or rendering one room-scoped, append-only ledger. The core is deliberately held to six primitives · declarations, conversations over declarations, derived signals, sealed payloads, numbers, views · with an explicit test written into the architecture doc: which primitive is this feature, and if it needs a seventh, reject it or redesign it. The doc names the one place the test genuinely fails, gates, and flags a second as benign rather than smoothing either over. On the wire that ledger is a closed zod discriminated union of 23 RoomEvent variants, which is what makes the privacy claim structural instead of a policy: there is no variant that could carry source code.

The MCP surface is 29 tools registered unconditionally across 9 groups, rising to 34 only when room view, code sharing and session handoff are all enabled. That whole matrix is asserted in one test, because docs and marketing both cite the number and it had already drifted once. Reads ride a single rail: `get_team_context` returns teammates' intent, current contracts with versions and dependencies, changed-contract alerts, direct messages and pinned state, and it consumes a cursor so each event is delivered exactly once. `await_team_events` long-polls up to 28 seconds under the hosted function's 30-second budget, which gives cross-agent live push with no hooks and no tmux. Three MCP resources expose room state, contracts and presence. An A2A agent card advertises four skills mirroring the four core MCP tools one-to-one, though only `message/send` is implemented; streaming and task lifecycle are an open TODO.

The hosted rail is a Next.js 16 route handler that resolves a hashed bearer token to a room and member, rate-limits at 120 tool calls per minute per token, and records a per-tool audit row. Durability is Supabase Postgres with RLS, Realtime on the events, rooms, room_members and room_chat_events tables, and Postgres full-text search behind `search_memory`. RLS is not asserted against mocks: `packages/db` boots PGlite in-process, installs the minimum Supabase environment the policies depend on, applies every real migration file in order, and runs the policy tests under `set role` with JWT claims set, so the tests run against the exact SQL that ships.

The repo is a pnpm and Turborepo monorepo of six workspace projects: packages/{shared,cli,db}, apps/{web,desktop}, and an experiment package. The CLI is built with tsup and carries a forked local room server, Claude Code hooks, a tmux push bridge, a statusline, a `listen` delivery daemon, E2EE code sharing and session handoff, git worktree allocation and the pre-commit contract gate. The desktop app is Tauri 2 with real PTY terminals in Rust and a plain-TypeScript Vite frontend, and it renders the real web dashboard as a child webview rather than an iframe: the web app sends X-Frame-Options DENY on every path but /demo, and a child webview is a top-level browsing context, so the header does not apply and auth cookies stay first-party. The single most expensive build trap is written into both README and CLAUDE.md · the CLI and web app resolve the shared package through its dist build output, not its source, so the shared build must run before any test result is trusted.