agentsync

# agentsync

<!-- mcp-name: io.github.jarmstrong158/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

```bash
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](https://cli.github.com), authenticated with `repo` scope:

```bash
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`:

```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"
      }
    }
  }
}
```

| env var                   | required | default     | meaning                                    |
|---------------------------|----------|-------------|--------------------------------------------|
| `AGENTSYNC_BOARD_REPO`    | yes\*    | —           | path to the clone that **holds the board** |
| `AGENTSYNC_REPO`          | no       | —           | legacy alias for `AGENTSYNC_BOARD_REPO`    |
| `AGENTSYNC_AGENT_ID`      | yes      | —           | your unique agent id                       |
| `AGENTSYNC_REMOTE`        | no       | `origin`    | git remote name                            |
| `AGENTSYNC_BRANCH`        | no       | `agentsync` | coordination branch name                   |
| `AGENTSYNC_PARTNER_GITHUB`| no       | —           | partner GitHub user(s) to invite (comma/space-separated) |
| `AGENTSYNC_STALE_HOURS`   | no       | `24`        | age after which an in-progress claim is flagged `stale` |
| `AGENTSYNC_GIT_TIMEOUT`   | no       | `25`        | seconds any single git/gh call may run before it fails fast |

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 off