How it works
concord has three parts: a board that every agent reads and writes, jj workspaces that keep agents apart, and a gate that tests the combination before anything lands.
The stack
| Layer | Choice | Why |
|---|---|---|
| Isolation | jj workspaces, one per agent | merges and rebases never block; undo is always available; light |
| Coordination | the concord board | the only layer that prevented semantic bugs |
| Merge driver | Mergiraf | resolves same-function conflicts git cannot |
| Landing | concord gate | the only layer that detected every semantic bug |
The board
The board is one JSON file, state.json, in a concord/ folder inside the jj repo store. Any workspace or subdirectory of a project reaches the same board through .jj/repo, and each project has its own. Every command checks and changes the board inside one exclusive flock.
A blocking command that has to wait releases the lock and retries every 2 seconds. The board records each agent's last command, and a waiting command refreshes its own agent's record at most once a minute. That record is how concord tells a slow agent from a crashed one: 30 minutes of silence stops the wait with BLOCKED by <agent>.
Your repository
Nobody types a jj command. Without .jj, concord sets up jj colocated with git, and git keeps working. Your main workspace tracks files like git does: a new file stays untracked until you git add it. Agents start from your last commit, and your main folder is never an agent's workspace, so a session editing there without concord keeps its files.
History only grows. A committed change is never rewritten, and other agents' work comes in by merge, never by rebase. Plain git push and fetch keep every machine consistent.
Rust architecture
A functional core with an imperative shell around it:
| Module | Role |
|---|---|
core | Pure state machine: apply(Option<Board>, Command, now) -> Result<Step, Error>, where Step is Wait or Next(Board, Outcome). Barrier, queue order, idempotent plan, seen-set for contract notices. Every protocol rule lives here and is tested without a filesystem or processes. |
store | Loads and saves the board atomically under flock; the only module touching the board file. |
vcs | A fork of jj 0.47.1 used as a library, in-process: revsets, commit, new, rebase, abandon, bookmarks, Mergiraf through jj's merge editor. No subprocess, no jj binary. |
team | Project discovery, agent workspaces, and the check that worker commands run in their own workspace. |
gate | Combines finished work through vcs and runs the test command. |
serve, remote | The HTTP server (board API and git http-backend) and its client in a joined clone. |
cli | Argument parsing, waiting loops, exit codes. The concord and git-concord binaries both call concord::main. |
Open decisions
- Structured contracts:
donetakes--name --params --returns --format, so "now always float" cannot be left vague, and the gate can diff contracts against code. - Stable function identity: claim keys follow renames, so
totalandsubtotalare the same entity. - A speedup scenario: five or more agents on a real repository where most tasks are independent, to show the board does not over-serialize.
- Delivery: the CLI ships with an agent skill; an MCP server is the remaining option.