agentsync

Invite one or more people as collaborators on the shared repo so they can push to it. Use this when the repo already exists and you just want to grant partners access (provision() does this too, but only as part of first-time setup). This is how you build a team of more than two. github_username : one or more GitHub users, comma- or space-separated (e.g. "jarmstrong158" or "alice, bob, carol"). permission : pull | triage | push | maintain | admin (default push). Each invited user must accept the GitHub invitation before they can push. Requires the `gh` CLI authenticated with admin on the repo. Returns the clone URL to hand the new collaborators.

Detect conflicts between your branch and your partners' branches. Reports two levels: claim_overlap : set intersection of touched files (intent level) merge_conflict : a real dry-run merge via `git merge-tree` (textual) against_branch lets you check one specific branch; default checks every branch named in a peer's active claim. Your own branch is taken from your current claim. claim_overlap is intent-level, so it only exists where intent was declared. If against_branch names a branch no active claim mentions, claim_overlap is reported as an explicit {"status": "unknown"} object naming the reason — never as an empty list, which would read as a verified all-clear.

Stake a claim on a unit of work, so a partner cannot start the same files underneath you. When to use this instead of the alternatives: claim : you are about to START work. Call it BEFORE editing, not after — a claim taken afterwards cannot prevent the collision it was meant to catch. survey : just look at who holds what, changing nothing. check_conflicts : you already hold a claim and want to know whether your branch now collides with a peer's. update_status : you already hold this claim and only the status or note has changed. Re-claiming to edit a claim replaces it. task : what you are building, in a few words. This is what a partner reads in survey() to decide whether your work blocks theirs, so "migrate the auth middleware" beats "fixes". touches : files/modules you will modify — the "get in the way" check. Overlap is set intersection against peers' touches, so name the real paths you will edit; a directory only matches a peer who named that same directory, not files inside it. requires : files/modules you depend on but will NOT edit (omit if none) — the "rely on their build" check. branch : the branch your work will live on force : claim even if an overlap with an active peer claim is detected. Use it only after talking to the peer; it does not resolve the collision, it just proceeds despite it. Refuses (status="blocked") if your plan collides with a peer's active claim, returning exactly what overlaps and with whom, unless force=True. The overlap is evaluated against freshly fetched state immediately before the push, so a peer who claimed first will be seen here.

Close the loop: mark your claim done AND open a GitHub pull request from your claimed branch into the default branch, so your work lands in review. note : PR body (falls back to your claim's existing note). title : PR title (falls back to your claim's task). draft : open the PR as a draft. Your branch must already be pushed. If a PR for the branch already exists, its URL is returned instead of erroring. Requires the `gh` CLI. The claim is marked done (with auto-captured `changed_files`) after the PR is opened.

The coordination timeline: who claimed, finished, or released what, and when — read from the git history of claims.json. Newest first. `limit` caps how many events are returned. Useful for 'what has my partner been doing?' without needing them online.

Create the shared GitHub repository if it doesn't exist yet, then leave both collaborators ready to use the claim protocol. Run this ONCE, by one person, before anyone calls survey()/claim(). It is idempotent — safe to re-run; each step is skipped if already done. What it does, in order: 1. Ensure AGENTSYNC_REPO is a local git repo with at least one commit (creates the directory + a starter README if empty). 2. Create the repo on GitHub via `gh` (private unless private=False) and wire up the 'origin' remote, or reuse an existing remote/repo. 3. Push the default branch. 4. Seed the coordination branch (agentsync) with an empty claims.json. 5. Invite the partner(s) as push collaborators, if any usernames are given here or via AGENTSYNC_PARTNER_GITHUB. repo : 'owner/name', bare 'name' (owner = you), or '' to use the AGENTSYNC_REPO folder name. partner_github : one or more GitHub usernames to invite, comma- or space-separated (overrides env). Supports a whole team. private : create the repo private (default) or public. description : optional GitHub repo description. Requires the `gh` CLI, authenticated (`gh auth login`) with 'repo' scope. Returns a summary of what was created plus the clone URL to send your partners.

Abandon your current claim WITHOUT marking it done, freeing the files you were holding so a partner can take them over. Use this when you're dropping the task or stepping away — otherwise a crashed or abandoned claim blocks those files indefinitely (the only other exits are 'done' or manual git surgery). Pushes immediately. note : optional free text recording WHY you are dropping the claim, e.g. "blocked on the API rewrite, not started" or "handing over to Sam". It replaces the claim's existing note and is what a partner reads in history() when deciding whether to pick the work up, so a released claim with no note leaves them guessing whether anything was done. Only your OWN claim can be released; you cannot release a partner's. The release is recorded in history rather than erased, so the attempt is still visible afterwards. Returns JSON with the released claim, or an error if you hold no active claim.

Pull the latest coordination state and report what every *other* agent has claimed: task, files touched, dependencies, branch, status, timestamp. Works for any number of collaborators, not just one. Each partner entry is annotated with `age_hours` and a `stale` flag (an in-progress claim older than AGENTSYNC_STALE_HOURS, default 24h) so you can spot a partner who may have crashed or wandered off still holding files. Call this before planning and again after finishing work.

Update your own claim's status (e.g. 'in-progress' -> 'done') and optionally attach 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). To drop a claim without finishing it, use release(); to finish AND open a PR, use finish().