</aethereum>
A shared brain for AI coding agents: contracts sync before anyone commits.

4
MCP primitives, the whole tool surface
MCP · A2A
protocols shipped, zero lock-in
553
automated tests passing in CI
cross-machine
contract sync before anyone commits
SPECIFICATIONS
| ROLE | SOLO BUILD |
|---|---|
| YEAR | 2026 |
| TYPE | CLI · MCP · WEB |
| STATUS | LIVE |
| STACK | typescript · pnpm · turborepo · mcp · a2a · claude code · supabase · realtime +3 more |
| LINKS | [live ↗][github ↗] |
| AVAILABILITY | aethereum.dev |
“Teams running AI coding agents have no shared context across developers and machines.”
dev.Developers keep using native Claude Code (or Cursor, or Codex) · their agents silently share interface contracts, intent, collision alerts, and direct messages across machines, so one agent writes the correct code before the other dev has even committed.js 16 API.
== WHAT IS THIS ==
A shared brain for AI coding agents, live at aethereum.dev. Developers keep using native Claude Code (or Cursor, or Codex) · their agents silently share interface contracts, intent, collision alerts, and direct messages across machines, so one agent writes the correct code before the other dev has even committed. A pnpm + Turborepo monorepo: a room-server CLI built from scratch, an MCP + A2A tool layer, a serverless skills marketplace, and a hosted Supabase realtime sync layer behind a thin Next.js 16 API.
== </the problem> ==
Teams running AI coding agents have no shared context across developers and machines. One agent declares an interface; another, on a different laptop, builds against a stale assumption of the same interface. The mismatch only surfaces at merge time, after both agents have committed to incompatible shapes. The gap the built-in agent-team features leave open is the cross-machine, uncommitted-contract case · the thing git and same-machine frameworks can't see.
== </my approach> ==
Give the agents a shared brain without changing how developers work. Built the room-server transport from scratch, then put the real design effort into reshaping the payload into four structured primitives · intent, contracts, collision alerts, and direct messages · mirrored to a hosted Supabase realtime sync layer, with an A2A interop surface and a serverless skills marketplace on top. Developers keep using native Claude Code, Cursor, or Codex; their agents publish and read context silently underneath.
== </the story> ==
Aethereum started from a real friction on any team running AI coding agents: two developers, two agents, two machines · and no shared context between them. One agent invents a function signature while another, on a different laptop, builds against a stale assumption of the same interface. The code only collides at merge time, long after both agents have committed to incompatible shapes.
Aethereum gives a team's agents a shared brain. Developers keep using their own agent · Claude Code, Cursor, Codex, any MCP client · with zero new workflow. Underneath, their agents silently publish to a shared room: what they're building right now (intent), the interface contracts they declare, collision alerts when a contract another agent depends on changes, and direct messages to each other. The result is that one agent can write the correct code before the other developer has committed anything.
The wedge · and the durable gap versus the free agent-teams features shipping inside the tools themselves · is the cross-machine, uncommitted-contract case. Sharing intent and contracts that only exist in one developer's working tree, across separate machines, in real time, is the thing git and same-machine frameworks can't see. Aethereum protects that framing in every surface.
It shipped across eleven phases and is live at aethereum.dev, free to get started. I built the transport layer myself · a local room server, server-sent events, a tmux push bridge that injects straight into a live agent session, and an optional tunnel · then put the harder effort into the part that's actually novel: reshaping freeform chat into structured intent, versioned contracts, alerts, and messages, with a hosted realtime sync layer, an A2A interop surface, and a serverless skills marketplace built on top.
== </architecture> ==
Aethereum is a pnpm + Turborepo monorepo built around a room-server engine written from scratch. The engine lives consolidated in one package · a room server (HTTP + SSE), an MCP tool layer fused with the agent runtime, and a tmux push bridge that injects events into a live agent session · published to npm under Aethereum's own name.
The runtime path: Claude Code, launched through Aethereum's wrapper, talks to MCP tools and the tmux bridge, which connect to the local room server over HTTP and SSE. The room server is the runtime source of truth; it mirrors state over HTTPS to Supabase (Postgres with Row Level Security, Auth, Realtime), which is the durable store and the backing for the live dashboard. A hosted MCP transport gives zero-install cross-machine tools; an optional Cloudflare tunnel exposes a self-hosted room across machines.
The core surface is four primitives · share_intent (what I'm building now), declare_contract (register or update an interface contract, with dependency links), get_team_context (teammates' intent, current contracts, changed-contract alerts, and installed skills), and send_message (directed or broadcast agent-to-agent, exactly-once). Events are a typed zod discriminated union shared across packages; the collision engine does a dependency-aware diff on contract versions and pushes alerts only to the agents that depend on what changed, exactly-once via a cursor rail. An A2A surface (/.well-known/agent-card.json + JSON-RPC) lets external agents interoperate, and a serverless skills marketplace injects installed instruction bundles straight into get_team_context · no webhooks, no code execution, nothing leaves the team. The hosted sync API is a thin set of Next.js 16 route handlers with hashed-token auth, idempotent writes, and rate limiting · the Supabase service key never touches a client or CLI bundle, and CI fails the build if it ever appears in an artifact.
== </key features> ==
Four core primitives
share_intent, declare_contract, get_team_context, and send_message over MCP + SSE. Everything else is a surface over these four. The core surface does not grow without cause.
Cross-machine contract sync
Interface contracts that only exist in one developer's working tree are shared across separate machines in real time, before anything is committed.
Dependency-aware collision alerts
A version diff on contracts pushes an alert only to the agents that actually depend on what changed, exactly-once via a cursor rail · amber as punctuation, not noise.
A2A interop + skills marketplace
An agent-card + JSON-RPC surface lets external agents interoperate, and a serverless marketplace injects installed instruction bundles into team context · no webhooks, no code leaves the team.
Plugs into the tools a team already uses
GitHub PR comments on contract-breaking changes, Slack and Discord alerts, two-way Linear ticket sync, outbound webhooks, and a public read API · room integrations are opt-in per room, so nothing is connected until you connect it.
Never blocks the agent
Offline or unreachable, the MCP layer degrades silently. It is an augmentation, never a dependency the agent can trip over. Stores only what an agent explicitly publishes · never source code.
Production-grade monorepo
pnpm + Turborepo, strict TypeScript, typed zod events, 553 tests, RLS verified against real Postgres, and a secret-leak CI guard. Eleven phases, shipped and live.
== </key decisions> ==
DECISION 01
Build the transport once, plainly, and put the novelty budget into the payload. A room server, SSE fan-out, a tmux bridge that injects into a live agent session, and tunnelling are all fiddly to get right but not where Aethereum needed to be original, so I wrote them the boring, well-understood way and spent the actual design effort on the part that's genuinely novel: turning freeform chat into structured intent and versioned contracts with collision detection. Nothing about the transport is borrowed from elsewhere · the discipline was in not over-engineering it.
DECISION 02
Hold the core to a handful of primitives. The temptation in a tool like this is to keep adding concepts. Aethereum holds the line at intent, contracts, context, and messages, and treats every other feature · dashboard, skills marketplace, A2A, auto mode · as a surface over those four. Reliability and surfaces get added; new core concepts don't.
DECISION 03
The MCP must never block or break the agent. If Aethereum is offline or the room is unreachable, the layer degrades silently and the agent keeps working · it's an augmentation, never a dependency. Privacy is a hard constraint, not a setting: Aethereum stores only the contracts, intent, and events an agent explicitly publishes, never source code, and the architecture is built so that's provably true.
DECISION 04
Ship production-grade, the name last. The whole thing runs on a strict-TypeScript monorepo with per-package tests (553 passing in CI), a lint/typecheck/test/build CI gate, RLS verified against real Postgres, and a secret-leak guard · not an MVP bar. Every user-facing name is routed through a single brand constant, so settling on the final Aethereum name late in development · after building for months under an early working codename · was a one-line change instead of a scattered rename across the codebase.
== </what i learned> ==
Building the transport plainly and saving the novelty budget for the payload beats over-engineering the boring parts. A room server, SSE fan-out, and a tmux bridge don't need to be clever · the actual differentiation is entirely in the intent/contracts model layered on top.
A small primitive core is a feature, not a limitation. Holding the surface tight keeps the product legible and the durable wedge protected even as A2A, skills, and a dashboard get layered on.
Routing every user-facing name through a single brand constant made settling on the final Aethereum name late in development a one-line change instead of a scattered rename.
typescript · pnpm · turborepo · mcp · a2a · claude code · supabase · realtime · postgresql · zod · next.js
LIVE · aethereum.dev