A coordination protocol for trees of Claude Code agents.

One goal in, multiple agents out. They decompose, parallelize, wait on dependencies, and synthesize — all through a shared SQLite database.

$ cord run "Build a competitive landscape report for fintech" --budget 5.0

cord run

  ● #1 [active] GOAL Build a competitive landscape report for fintech
    ✓ #2 [complete] TASK Identify top fintech competitors
      result: Task complete. JSON array with top 10 fintech companies...
    ✓ #3 [complete] TASK Research fintech industry trends
      result: Task complete. Compiled trends across regulatory, AI...
    ● #4 [active] TASK Deep competitive analysis
      needs: #2, #3
    ○ #5 [pending] TASK Write executive report
      needs: #4

  running: #1, #4

The root agent decided to split the work into 4 tasks. #2 and #3 ran in parallel. #4 needs results from both research tasks — their full results are injected into its prompt. #5 waits for #4. When everything completes, #1 relaunches to synthesize the final report.

No workflow was hardcoded. The agent built this tree at runtime.

• uv (Python package manager)
• Claude Code CLI installed and authenticated (claude command available)
• An Anthropic API key with sufficient credits

git clone https://github.com/kimjune01/cord.git
cd cord
uv sync

# Give it a goal
cord run "Analyze the pros and cons of Rust vs Go for CLI tools"

# Or point it at a planning doc
cord run plan.md

# Control budget and model
cord run "goal" --budget 5.0 --model opus

Options:

You                    Engine                 Agents
 │                       │                      │
 │  cord run "goal"      │                      │
 │──────────────────────>│                      │
 │                       │  create root in DB   │
 │                       │  launch root agent   │
 │                       │─────────────────────>│
 │                       │                      │ create("#2", ...)
 │                       │                      │ create("#3", ...)
 │                       │                      │ complete("decomposed")
 │                       │<─────────────────────│
 │                       │                      │
 │                       │  #2 and #3 ready     │
 │                       │  launch both         │
 │                       │─────────────────────>│ (parallel)
 │                       │                      │ complete("result")
 │                       │<─────────────────────│
 │                       │                      │
 │                       │  all children done   │
 │                       │  relaunch #1 for     │
 │                       │  synthesis            │
 │                       │─────────────────────>│
 │                       │                      │ complete("final report")
 │  TUI: all ✓           │<─────────────────────│
 │<──────────────────────│                      │

Each agent gets MCP tools to coordinate:

Agents don't know they're in a coordination tree. They see MCP tools and use them as needed. The protocol — dependency tracking, authority scoping, result injection — is enforced by the MCP server.

needs — when creating a child task, list the node IDs whose results it depends on. The engine won't launch the child until all needed nodes complete. Their full results are injected into the child's prompt. This is the single context-engineering primitive: you choose which results flow to each child.

Context rot — if a child would need results from many nodes, create an intermediate task to synthesize them first. Each level of tree depth is a natural compression boundary. Prefer deeper trees over wide fan-ins.

Two-phase execution — an agent decomposes (creates children, calls complete). The engine waits for children. When all children finish, the engine relaunches the parent with a synthesis prompt that includes children's results.

Authority — agents can only create children under themselves and stop nodes in their own subtree. They can't touch siblings or ancestors.

src/cord/
    cli.py                  # cord run "goal"
    db.py                   # SQLite (CordDB class, WAL mode)
    prompts.py              # Prompt assembly for agents
    runtime/
        engine.py           # Main loop, TUI
        dispatcher.py       # Launch claude CLI processes
        process_manager.py  # Track subprocesses
    mcp/
        server.py           # MCP tools (one server per agent)

~1020 lines of source. SQLite is the only dependency beyond the MCP library.

uv run pytest tests/ -v   # 49 tests

experiments/behavior_compare.py runs 8 behavioral tests against both Opus and Sonnet via Claude Code CLI, comparing how each model uses the Cord MCP tools. The earlier behavior tests (see BEHAVIOR.md) were run against the v0.3 API which used separate spawn/fork primitives — these have since been unified into create with explicit needs.

The pause, resume, and modify tools were added because Claude independently tried to call them before they existed (BEHAVIOR.md test 13). We built what the model already expected.

Each agent subprocess has its own Claude API budget (set via --budget). A simple 2-node task costs ~$0.10. The demo fintech report (4 agents + synthesis) costs ~$2-4. Costs scale with the number of agents and their complexity.

• Single machine only. Agents are local processes.
• No web UI — terminal TUI only.
• No mid-execution message injection (pause/modify/resume requires relaunch).
• Each agent gets its own MCP server process (~200ms startup overhead).
• Claude Code CLI must be installed and authenticated.

This repo is one implementation of the Cord protocol. The protocol itself — four primitives, dependency resolution, authority scoping, two-phase lifecycle — is independent of the backing store, transport, and agent runtime. You could implement Cord with Redis pub/sub, Postgres for multi-machine coordination, HTTP/SSE instead of stdio MCP, or non-Claude agents. See RFC.md for the full protocol specification.

MIT