chord

Run coding agents as a cluster.

One repository, as many agents as you care to start. Each agent works in its own worktree; a shared board records who holds which file; an agent that wants a file another agent holds asks first and waits for the answer; when the work is committed, one call rebases the branch and fast-forwards main. Idle agents are woken the moment a message arrives, so the agents negotiate among themselves while you keep handing out work in plain language.

✨ Highlights

• One repository, N agents, one worktree each: parallel work without stepping on each other
• A file-level claims board: register before editing, talk to the holder first, and a hook turns away any write that was never claimed
• Asynchronous messaging between agents: idle ones are woken, busy ones hear at their next tool call
• finish in one step: rebase, fast-forward main, release the claims, tell the others; on a conflict nothing changes and the agent is told to rebase, resolve it and finish again, asking you only if it cannot
• Agents learn the rules from chord itself, at start-up and on every prompt; you give tasks, not instructions about chord
• Agent-agnostic by design: adding a tool means one launch recipe, not a new coordinator
• chord ls for the whole picture, messages and events to replay what happened, stop and clean to wind down

📊 Benchmark

On CooperBench two agents each take one feature in the same repository, and a pair passes when the merged result passes the tests of both features.

On the stronger model chord keeps pace with the best baselines. On the weaker one it is the only two-agent setup that does not fall below a single agent, and it beats the team setting by 20 points. chord's agents got only the feature text, while the coop + git and team prompts spell out how to split and merge the work.

🤖 Supported agents

A new agent needs three things from its tool: a way to inject hooks and an MCP server at launch, the names and payloads of its hook events, and an idle/busy signal.

🧩 How it works

1. Isolation. Every agent works on its own branch in its own worktree. The main checkout changes through finish alone.
2. Coordination. A shared board holds claims, messages and events. Agents register, claim and talk through tools chord gives them; hooks check claims before each write and hand new messages to the agent as it works.
3. Merging. finish rebases the branch onto main and fast-forwards. A clean rebase that passes the project's test command merges; on a conflict nothing moves, and the agent resolves it and finishes again.

📦 Install

With Node 24 and git on the machine:

npm install -g chord-cli

On Linux add --allow-scripts=node-pty, with python3, make and g++ present: node-pty ships no Linux binary and builds one on install. macOS needs nothing more: node-pty ships a binary for it.

Or from source:

git clone https://github.com/Cedr1cSun/chord-cli && cd chord-cli
npm install && npm link

🚀 Quick start

A project is a folder with the repository in a child directory:

my-project/
  my-repo/        the main checkout
  chord/          chord's own files, outside the repository

In the project folder, one terminal per agent:

chord claude                                     # start an agent
chord codex --name api                           # start another, named
chord opencode --name web                        # any mix of tools
chord pi --name docs
chord claude "fix the flaky test in tests/auth"  # arguments after the tool name go to the tool

Hand out tasks in those terminals as you always would. From another terminal:

chord ls                 # agents, what they are on, unread messages, branch state, file claims
chord messages api       # what an agent has said and been told
chord events             # claims, releases, merges, conflicts
chord stop api           # let it finish its turn, then quit
chord clean              # remove the workspaces and branches of agents that have left

--name fixes an agent's name, workspace and branch, so launching the same name later returns to the same worktree. chord resume <agent> does that and also reopens the agent's own conversation, for Claude, Codex, OpenCode and pi alike. Run chord in a repository root and it offers to move the repository into a child directory first.

Agents start in the project folder, the same directory you run plain claude, codex, opencode or pi in, so that stays their project too: one /resume list, one CLAUDE.md, one trust answer. Each agent edits only its own worktree under chord/agents/<name>/; chord refuses edits (editor tools, apply_patch) to the main checkout and to other agents' worktrees, and tells the agent off after a shell command that ran there.

🧰 Commands

⚙️ Configuration

<project>/chord/config.json:

{ "setup": "npm ci", "test": "npm test" }

setup runs once in every new worktree before the agent starts, with the CHORD_* variables in its environment, so a fresh worktree arrives with its dependencies in place. A failed setup abandons the launch and removes the worktree.

test, when set, runs in the agent's worktree each time finish has rebased the branch onto main, before main moves. If it fails nothing is merged and the agent gets the end of the output: a clean rebase can still break what another agent merged. Other agents' finish waits while it runs.

A repository's own Claude configuration (.claude/settings*.json, .mcp.json) reaches an agent once you have trusted that repository, or the project folder, in Claude Code yourself; the MCP servers you approved there are the ones that start.

🔌 How chord works with your tools

• Waking an agent means typing a short note into its terminal. chord does this only when the input box is empty, the keyboard has been quiet for a few seconds, and the terminal has echoed the note; a dialogue never receives the Enter.
• Trust: agents run in the project folder, so Claude asks about it once, as it does for plain claude; chord writes nothing to ~/.claude.json. Codex asks you to review chord's hooks once, and again whenever their definition changes; answer "trust all". chord says so at launch if a hook has been switched off. OpenCode asks nothing: chord hands it the plugin and the MCP server through OPENCODE_CONFIG_CONTENT, so a configuration of your own set in that variable is not read while an agent runs; your global config, OPENCODE_CONFIG_DIR and the project's opencode.json are. pi asks nothing either: chord loads its extension with -e and the extension registers the MCP server for that session, so ~/.pi is not written to.
• Branches and worktrees. Each agent adds a chord/<name> branch and a worktree; chord clean removes them when the agent has left and keeps anything not yet on main.
• Permissions. chord's own tools are pre-approved for Claude, so an agent working on it