A tested local MCP server and collaboration hub that gives Claude Code, Codex, and a human one process for independent proposals, shared planning, cross-review, and delivery acceptance.
Python
SQLite
MCP
Claude Code Channels
Codex app-server
WebSockets
MCP + CLI interface
Built for agents and a human operator.
Tandem is a headless MCP server with a human CLI, a Claude Code adapter, and a Codex driver. Agents use protocol tools; the operator uses commands and the event feed. Its interface is the collaboration protocol, so a graphical application screen is not required. The architecture schematic documents the implemented components.
Business problem
Why this system exists
Two coding agents can produce competing plans and lose track of ownership, reviews, and the next decision when they work without a shared process. A human needs clear approval gates and an inspectable record of what happened.
Role evidence
What the repositories support
Repository evidence supports the workflow core, local hub, agent adapters, human CLI, versioned protocol, and verification work. Protocol conformance, 80 unit tests, and scripted lifecycle checks in both lead modes verify the local coordination process.
Repository group
Canonical private repository — source is not publicly linked
System architecture
Verified boundaries from interface to accountable data.
This diagram summarizes repository-supported components and controls. It does not imply that disabled providers or undeployed services are active.
01Participants and adaptersHuman CLI · Claude Code MCP adapter and Channels push · Codex app-server driver
03Workflow corePython state transitions · role checks · plan gates · cross-review · human acceptance
04Durable evidenceSQLite project, task, and event records · JSON-persisted Codex dispatch budgets and retry state
Architecture schematic · verified implemented components, not an application screenshot.
Core workflow
A controlled path from source to accountable action.
01proposing → synthesizing: each agent submits a blind proposal; the lead merges the plans
02synthesizing ↔ plan_review → awaiting_approval: the partner critiques and the human approves
03executing: agents perform dependency-ready tasks; the other agent reviews each submission
04delivering ↔ verifying → awaiting_acceptance → delivered: the partner verifies and the human accepts
AI boundary
Assistance without invented authority
The Claude MCP adapter and Codex app-server driver connect existing coding agents to the same workflow. Independent proposals, partner review, explicit human decisions, and agenda-driven dispatch keep collaboration attached to shared state and an event record.
Human approval points
Human plan approval by default; an explicit auto-approve option can skip that gate
The other agent reviews each task; repeated plan or task disputes escalate to the human
Partner delivery verification followed by human acceptance before the delivered state
Security controls
Separate participant tokens, hashed token lookup, private token files, and loopback listeners
Independent proposals remain hidden from the other agent until both are submitted
Peer text is framed as material to evaluate, not a new human instruction
The Codex driver denies approval requests and returns no structured input answers; human questions go through the hub
Reliability controls
Protocol 1.1 conformance passed; all 80 unit tests passed on Python 3.13.9
MCP SDK handshake, 19 exposed tools, and a live channel notification verified in a disposable local runtime
Fresh CLI lifecycle checks reached delivered with Codex and Claude selected as lead, using two scripted participants
Only events that add agenda work wake an agent; FYI chatter does not trigger turns
Codex defaults: 20 start/steer dispatches per rolling hour, a 900-second turn limit, and 5–300-second failure backoff
Current limitations
Runs locally on one machine; not a hosted service. A complete product run with both real agents through human acceptance is not verified.
Both lead modes were checked with two scripted participants and scripted human decisions, not real model calls. Historical real-agent checks were not rerun for this checkpoint.
Failures need a queued or new action-required wake, or a startup reminder, before retry; transport or app-server process failures require correction and restart.
Claude push relies on the development-channels flag; capped notifications may need another actionable event or session reminder.
Participant tokens are not product-tenant isolation. Reviews and workflow status do not guarantee product correctness or safe business behavior.
No measured productivity, cost, or quality improvement is claimed.
Evidence before adjectives
See how claims are admitted, withheld, and corrected.