Content
# agent-coord
A tiny, **zero-dependency** coordination layer that lets multiple coding agents
— **Claude Code**, **Codex**, or anything that speaks MCP — work on the same
repository at the same time without clobbering each other.
It solves a specific, real problem: when two agents run in parallel (e.g. each in
its own git worktree), they edit the same files, claim the same task, and
generally trip over each other. `agent-coord` gives them a shared **board** to
coordinate through:
- 🔒 **File locks** — reserve repo-relative globs before editing; others see them.
- 🧩 **Task claims** — claim a plan/task id so the other agent picks something else.
- 📣 **Status messages** — a lightweight broadcast channel between agents.
- 🛡️ **Hard enforcement on Claude Code** — a `PreToolUse` hook *blocks* edits to a
file another agent has locked, and *auto-claims* files Claude touches.
No SDK, no `npm install`, no database. The board is a single JSON file
(`~/.agent-coord/board.json`) guarded by an atomic, multi-process-safe mutex.
---
## How it works
```
Claude Code ──┐ ┌── Codex
(MCP client) │ stdio MCP ┌────────────┐ │ (MCP client)
├───────────────▶│ server.mjs │◀───┤
PreToolUse │ └─────┬──────┘ │ (cooperative:
hook (guard) │ │ │ calls the tools)
blocks edits ─┘ ┌─────▼──────┐ │
to locked files │ board.json │◀───┘
│ (shared) │
└────────────┘
```
- Every agent points at the **same board file**, which lives *outside* any
worktree — so locks made in worktree A are visible in worktree B.
- Locks are keyed on the **repo-relative path** (+ a project id derived from the
git top-level dir), so `src/cart.ts` is the same lock in every worktree of the
repo, and unrelated repos never collide.
- **Claude Code** gets *enforcement* (the hook can deny an edit). **Codex** has no
pre-tool hook, so it cooperates *voluntarily* by calling the MCP tools — which
is why the agent instructions (below) matter for it.
> Best paired with **separate git worktrees per agent**. With one worktree per
> agent, git itself handles file merges; `agent-coord` stops the two agents from
> duplicating work or racing the same file before it's committed.
---
## Install
```bash
git clone https://github.com/ThatHunky/agent-coord
cd agent-coord
node test/smoke.mjs # optional: verify (no deps required)
```
Requires Node ≥ 18. There is nothing to build.
### Wire up Claude Code
Register the MCP server (user scope, identity = `claude`):
```bash
claude mcp add agent-coord -s user \
-e AGENT_COORD_AGENT=claude \
-- node /ABSOLUTE/PATH/TO/agent-coord/src/server.mjs
```
Add the enforcement hook to `~/.claude/settings.json` (see
[`examples/claude-settings.json`](examples/claude-settings.json)):
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write|MultiEdit|NotebookEdit",
"hooks": [
{
"type": "command",
"command": "AGENT_COORD_AGENT=claude node /ABSOLUTE/PATH/TO/agent-coord/src/guard.mjs"
}
]
}
]
}
}
```
### Wire up Codex
Add to `~/.codex/config.toml` (see [`examples/codex-config.toml`](examples/codex-config.toml)):
```toml
[mcp_servers.agent_coord]
command = "node"
args = ["/ABSOLUTE/PATH/TO/agent-coord/src/server.mjs"]
env = { AGENT_COORD_AGENT = "codex" }
```
### Tell both agents to use it
Paste [`docs/AGENTS-snippet.md`](docs/AGENTS-snippet.md) into your project's
`CLAUDE.md` and `AGENTS.md` so each agent knows the protocol.
---
## MCP tools
| Tool | What it does |
|------|--------------|
| `coord_status` | Show the board: active locks, task claims, recent messages. **Call first.** |
| `coord_claim_paths` | Reserve repo-relative path globs; returns cross-agent conflicts. |
| `coord_release_paths` | Release a lock (`lockId`) or all of yours (`all: true`). |
| `coord_claim_task` | Claim a task/plan id; fails if another agent holds it. |
| `coord_complete_task` | Mark a claimed task done. |
| `coord_post` | Broadcast a status message. |
| `coord_whoami` | Show this agent's identity, project, and board path. |
## CLI (for humans)
Watch what both agents are doing, live:
```bash
agent-coord watch # live board for the current repo
agent-coord status [project] # one-shot
agent-coord post "message" # broadcast (set AGENT_COORD_AGENT first)
agent-coord locks # every lock across all projects
agent-coord clear # drop all of your agent's locks
```
(Run via `node src/cli.mjs …`, or `npm link` to get the `agent-coord` binary.)
---
## Configuration
All optional, via environment variables:
| Variable | Default | Meaning |
|----------|---------|---------|
| `AGENT_COORD_AGENT` | `unknown` | This agent's identity (`claude`, `codex`, …). **Set this.** |
| `AGENT_COORD_DIR` | `~/.agent-coord` | Where the shared board lives. |
| `AGENT_COORD_PROJECT` | git top-level basename | Project id for scoping locks. |
| `AGENT_COORD_LOCK_TTL_MINUTES` | `120` | Default lock expiry. |
| `AGENT_COORD_AUTOCLAIM` | `1` | Claude hook auto-claims edited files (`0` to disable). |
| `AGENT_COORD_AUTOCLAIM_MINUTES` | `20` | TTL for auto-claimed locks. |
| `AGENT_COORD_MAX_MESSAGES` | `50` | Message ring-buffer size. |
---
## Design notes & limits
- **Fail-open.** The Claude hook never blocks your work on a bug — any unexpected
error allows the edit. The only thing that denies is a genuine, unexpired lock
held by a *different* agent.
- **Locks expire.** They're a coordination hint with a TTL, not a permanent
reservation, so a crashed agent can't wedge the repo.
- **Codex is cooperative, not enforced.** Without a pre-tool hook, Codex respects
the board only by calling the tools. The agent instructions make that reliable.
- **One machine.** The board is a local file; this is for agents sharing a
filesystem, not across machines.
## License
MIT — see [LICENSE](LICENSE).
