agentsync

An MCP server that lets two (or more) AI agents collaborate on the same git repository without stepping on each other. Each agent declares what it's building before it builds, sees what its partner has claimed, and detects conflicts when work lands — all coordinated through the repo itself, with no lock server and no requirement that both agents be online at once.

How it works (one paragraph)

Coordination state is a single claims.json living on a dedicated agentsync branch (kept out of main, so it never pollutes your code history and isn't blocked by main's branch protection). Each agent's claim declares the work, the files it will touch, what it requires, its branch, and a status. Overlap is plain set intersection. Writes use a read-modify-write loop with git push as a compare-and-swap: if the push is rejected, the server re-fetches the latest claims and re-evaluates, so a colliding peer claim is observed before this agent's claim is committed. All git work happens in a private worktree under .git/, so your agent's actual code branch is never disturbed.

See DESIGN.md for the architecture rationale and AGENTS.md for the playbook your agent follows to drive the tools.

Install

pip install -r requirements.txt      # just `mcp`

For anything that talks to GitHub — provisioning a repo (provision), inviting a collaborator (add_collaborator), or opening a PR (finish) — you also need the GitHub CLI, authenticated with repo scope:

gh auth login        # one-time; check with `gh auth status`

Configure

Both collaborators add the server to their MCP client, each with their own agent id and their own local clone. See mcp.config.example.json:

{
  "mcpServers": {
    "agentsync": {
      "command": "python3",
      "args": ["/abs/path/to/agentsync_server.py"],
      "env": {
        "AGENTSYNC_BOARD_REPO": "/abs/path/to/the/clone/holding/the/board",
        "AGENTSYNC_AGENT_ID": "jonny"
      }
    }
  }
}

The agentsync branch is created automatically on the first survey() or claim() call against an explicitly addressed board — no manual setup.

Where the board lives (board addressing)

* The board is a shared, long-lived team artifact, not a property of whichever repo you happen to be sitting in. So its address is resolved independently of the session, in this order:

1. AGENTSYNC_BOARD_REPO — the explicit board address. This never follows the Xylem session pointer (~/.xylem/active_project.json).
2. AGENTSYNC_REPO — the legacy explicit pin; identical effect.
3. The current repo (session pointer, else the cwd's git root) — but only if that repo actually holds the coordination branch. The check is a real ref lookup (local head → remote-tracking ref → ls-remote), so this fallback can only ever select a repo that genuinely is a board.
4. Otherwise a ConfigError naming AGENTSYNC_BOARD_REPO — never a silent selection of a boardless repo.

survey() reports the board it actually read under board: {repo, source}, so "the team is quiet" and "I am looking at the wrong board" are distinguishable.

Why this order. Previously an unpinned server followed the session pointer blindly. The board therefore changed identity whenever the session changed project, and in any project that had never been provisioned it simply disappeared — reported downstream as "no coordination branch found" and treated as normal. cambium's distill() applies this exact same resolution, so the two halves of the suite can never disagree about where the board is.

Starting from nothing (no repo yet)

If the shared repo doesn't exist on GitHub yet, one person runs provision() once. Point AGENTSYNC_BOARD_REPO at the folder you want the project in (it can be empty or not yet created) and call:

provision(repo="you/our-project", partner_github="their-username")

This creates the GitHub repo (private by default), makes the first commit, seeds the agentsync coordination branch, and invites your partner as a push collaborator. It's idempotent — safe to re-run. Then send your partner the clone_url it returns; once they accept the invite and clone, both of you point the MCP server at your own clones and the normal protocol below takes over.

Tools

provision(repo="", partner_github="", private=True, description="") — one-time bootstrap when the shared repo doesn't exist yet. Creates the GitHub repo via gh, makes the first commit, seeds the agentsync branch, and invites the partner as a push collaborator. Idempotent. Returns the clone_url to hand your partner. (Needs the gh CLI authenticated with repo scope.)

add_collaborator(github_username, permission="push") — invite one or more people (comma/space-separated) to the existing shared repo so they can push (pull|triage|push|maintain|admin). Use this when the repo already exists and you just want to grant access — this is how you build a team of more than two. They must accept the GitHub invite, then clone. (Needs gh with admin on the repo.)

survey() — pull the latest state and report what every other agent has claimed: task, files, dependencies, branch, status, timestamp. Works for any number of collaborators. Each partner entry is annotated with age_hours and a stale flag (in-progress and older than AGENTSYNC_STALE_HOURS, default 24h), and a top-level stale_claims list — so you can spot a partner who crashed or walked away still holding files. Run it before planning and after finishing.

claim(task, touches, requires=None, branch="", force=False) — stake a unit of work. Refuses with status: "blocked" if your touches hits a partner's active files (you'd get in their way) or your requires hits their in-progress files (you'd build on unstable ground), returning exactly what overlaps and with whom. Overlap is path-aware: exact match, directory containment (src/api vs src/api/routes.py), and globs (src/**, *.py) all collide, and paths are normalized first (./auth.py == auth.py). The overlap is checked against freshly-fetched state immediately before the push. Pass force=True to claim anyway (e.g. same large file, disjoint regions). If your agent id already holds an in-progress claim written by a different server instance — another agent is live under the same id — claim() returns blocked with a shared_agent_id reason naming the task, branch and files that would be erased, because one id holds exactly one claim. Give each agent its own id; force=True overrides it for the legitimate case of a restarted server reclaiming its own slot, and then the result carries a warning listing the files that just lost their protection.

release(note="") — abandon your current claim without marking it done, freeing the files for a partner to take over. Use it when you drop a task or step away — otherwise a crashed/abandoned claim blocks those files until someone does manual git surgery. Pushes immediately.

check_conflicts(against_branch="") — after building, diff your branch against your partners' branches at two levels:

• claim_overlap — declared-path intersection (intent, path-aware).
• merge_conflict — a real git merge-tree dry-run merge (textual). Catches collisions the claims didn't predict.

Defaults to every branch named in an active peer claim; pass against_branch to check one specific branch.

update_status(status, note="") — set your own claim's status (planning | in-progress | done) and optionally leave a note for your partner. Pushes immediately. On done, the claim is auto-annotated with changed_files — your branch's diffstat vs the default branch — so your partner reconciles against real data, not just a hand-written summary. It is computed in the board repo, and a claim records a branch name with no repo qualifier, so changed_files_repo names the repo the diffstat actually came from: where you coordinate on a dedicated board repo, a same-named branch there will diff cleanly and produce a confidently wrong file list. Check the label before trusting the list. (To drop a claim without finishing it, use release().)

finish(note="", title="", draft=False) — close the loop: mark your claim done and open a GitHub pull request from your claimed branch into the default branch. Falls back to your claim's task/note for the PR title/body, and returns the existing PR's URL if one is already open. Your branch must be pushed. (Needs gh.)

history(limit=20) — the coordination timeline (who claimed, finished, or released what, and when) read from the git history of claims.json, newest first. Answers "what has my partner been up to?" even when they're offline.

The workflow (what your agent does)

0. provision(...) — once, only if the repo doesn't exist yet (then both clone)
1. survey() — what's my partner working on, if anything?
2. plan a slice that doesn't overlap their active work
3. claim(...) — if blocked, narrow the slice or wait
4. build on your branch
5. survey() again — where are they now?
6. check_conflicts() — does their landed work collide with mine?
7. reconcile (rebase/merge or flag) → update_status("done", ...) or finish(...) to also open a PR

The full prompt your agent should run is in AGENTS.md.

More than two agents

Nothing here is limited to two. claims.json is keyed by agent id, claim() checks your plan against every peer, and the compare-and-swap only ever edits your own key — so three, four, or more agents coordinate safely. To run a team:

• Invite everyone: add_collaborator("alice, bob, carol") (or list them in provision(partner_github=...)).

• Give every agent a unique AGENTSYNC_AGENT_ID — every agent, not every person. One person running a desktop session, a phone and a remote agent needs three ids, for the same reason three people do: one id holds exactly one claim. claim() blocks rather than overwriting a live claim under your own id, but a unique id per agent avoids the collision entirely.

  This guard used to key on a per-process token, which meant it caught a restarted server and waved through a concurrent session -- one agentsync process serves every session on a machine, so two sessions shared the token and silently overwrote each other. It now keys on the work: a claim for a different task, while one is in progress under your id, is refused whatever process wrote it. Re-claiming the same task stays free, which is how you widen touches mid-unit. release(expect_task=...) covers the other direction, refusing to close a claim that is not the one you think you hold.

• Contention stays cheap for a handful of agents; with many simultaneous claimers a claim() can return retry_exhausted — just call survey() and retry.

Test

python3 test_agentsync.py     # unit + protocol suite (real git repos)
python3 test_workflow.py      # two-person lifecycle + real MCP stdio transport

test_agentsync.py (51 cases, isolated per test) covers the protocol (claim/ block on shared files and dependency-on-WIP, force override, done-claims-don't- block, status validation), path-aware overlap (directory containment, globs, normalization, disjoint-dirs-are-clean), conflict detection (textual conflict and clean-merge), the compare-and-swap guarantee (a peer claim landing mid-flight both survives our retry and is observed in time to block a collision), liveness (release, stale flagging, the live-claim guard against concurrent sessions), the review loop (history timeline, done diffstat capture, finish opening/reusing a PR, push-required guard), error paths, and provisioning + add_collaborator (single and multi-invite, partner-from-env, existing-remote skip, invite-failure reporting, bad-permission, no-remote) with the gh CLI stubbed so no real GitHub repo is touched. test_workflow.py (5 cases) drives the full two-person lifecycle and the real MCP stdio transport as a subprocess. CI runs both on every push via GitHub Actions.

Limitations

• Textual, not semantic. check_conflicts catches files that won't merge; it does not catch "their API signature change breaks my caller." That reasoning is the agent's job (read both diffs) — the server gives it the signal, not the judgment.
• Both sides must opt in. This only works fully if your partner's agent runs the same server and honors the same claim protocol. Without that, yours degrades to branch inspection: it sees what has landed, not what's planned.
• Advisory locks. Claims prevent collisions by convention, not enforcement; force=True exists precisely because some overlaps are fine.

License

PolyForm Noncommercial License 1.0.0 — free to use, modify, and share for any noncommercial purpose. Commercial use requires a separate license.