CLI Reference

Invocation

agentsync <command> [options]

Package: @remotehostai/agentsync. Bin: agentsync.

Global behavior:

• Every command reads .agentsync/config.yaml from the repo root (or the nearest ancestor).
• If coordinator.url is empty, commands run in advisory mode and print a one-line banner: advisory mode (no coordinator): coordination is best-effort, not guaranteed.
• Exit codes: 0 success, 1 generic error, 2 usage error, 3 conflict/denied (a claim or land was refused), 4 not initialized (no .agentsync/).

Commands

agentsync init

Initialize AgentSync in the current repo.

• Creates .agentsync/ with config.yaml (from the canonical default), tasks/, claims/, events.log.
• Installs the git pre-commit and pre-push hooks (backs up any existing hooks first).
• Adds runtime paths (CONTEXT.md, state/) to .gitignore.
• Detects the git remote and default_branch and writes them into config.yaml.

Options: --coordinator <url> to set coordinator.url at init time (otherwise advisory).

Output: a checklist of what was created. Exit 0, or 1 if not a git repo.

agentsync task create "<title>"

Create a task in the registry.

• Allocates the next AG-NNN id, derives a slug from the title.
• Writes tasks/AG-NNN.yaml with status: planned, base_branch set to default_branch, and the branch name from branches.pattern.

Options: --id <AG-NNN> to force an id, --actor <actor_id> to assign.

Output: the created task id and branch name.

agentsync checkout <task_id>

Create and switch to the task's branch using branches.pattern.

• Requires a clean worktree if branches.require_clean_worktree is true.
• Records the base_sha (current default_branch head) onto the task.

Output: the branch checked out and its base SHA.

agentsync claim <glob>...

Claim paths for the current task and actor.

• With a coordinator configured: requests a grant from the coordinator. On grant, writes the mirror to claims/<actor>.json with the fence_token and lease_expires_at, and appends a claim event.
• In advisory mode: writes the mirror and warns it is not guaranteed.
• exclusive_paths overlaps are denied; shared_paths overlaps are allowed with a warning.

Options: --intent write|read (default write), --ttl <duration> to override claims.lease_ttl.

Output: granted paths and lease expiry, or on denial the conflicting actor and a suggested wait/rebase. Exit 3 on denial.

agentsync status

Show the live landscape for this repo.

• Active tasks and their branches.
• Active claims (actor, paths, lease remaining, fence token when a coordinator is configured).
• Stale branches (base SHA behind default_branch).
• Work marked ready.

Output: a compact table. In advisory mode, reflects committed claims only.

agentsync conflicts

Predict conflicts across active branches.

• Checks path-claim overlap, actual-file overlap, hunk overlap (via git merge-tree), and stale-base risk.

Output: ranked branch-pairs with risk and the reason (which paths/files/hunks). Exit 0; exit 3 if --strict and any real hunk overlap is found.

agentsync merge-plan

Recommend a safe merge order.

• Topological order, lowest-conflict-first, with must-resolve-first items and stale-branch rebase flags.

Options: --json for machine-readable output.

Output: an ordered list of branches with notes.

agentsync ready [task_id]

Mark a task ready for review.

• Sets the task status: ready, appends a ready event. With a coordinator configured, this broadcasts to subscribers.

Output: confirmation. Defaults to the current branch's task if task_id is omitted.

agentsync commit -m "<message>"

Wrap git commit and append the agent footer.

• Validates the message against commits.style (conventional) if configured.
• Appends the trailer block: Agent, Task, Base-SHA, Claimed-Paths (from the active claim).
• Refuses (exit 3) if the staged change touches a path held by another actor's live claim (coordinated mode), or warns (advisory mode).

Options: --no-footer to skip the trailer (only if require_agent_footer is false).

agentsync push

Push the current branch.

• Runs the pre-push hook, which calls verify-land when a coordinator is configured. A push that violates a live claim or carries a stale fence token is rejected (exit 3).

agentsync release [glob]...

Release claims for the current actor.

• With no args, releases all of the actor's claims. With globs, releases the matching ones.
• Appends a release event. The happy-path counterpart to lease expiry.

Git-hook entry points

Invoked by the installed hooks, not by hand.

• agentsync check-commit <file>... — used by pre-commit. Exit 3 blocks the commit.
• agentsync check-push <ref>... — used by pre-push; calls verify-land. Exit 3 blocks the push.

agentsync context

Print (and refresh .agentsync/CONTEXT.md with) the live landscape — the same content the shared-context subsystem exposes. Safe for an agent to read at any time.