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.

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.

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.

Stake a claim on a unit of work.

touches : files/modules you will modify requires : files/modules you depend on (omit if none) branch : the branch your work will live on force : claim even if an overlap with an active peer claim is detected

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.

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.

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.

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().

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.