Getting Started

Install

npm i -g @remotehostai/agentsync

This installs the agentsync command.

Initialize a repo

From inside a git repository:

agentsync init

This creates .agentsync/ (config, task registry, claim mirror, event log), installs the pre-commit and pre-push git hooks, and detects your remote and default branch.

With no coordinator.url configured, AgentSync runs in advisory mode: coordination is best-effort, not guaranteed. To get the deterministic guarantee, point it at a coordinator:

agentsync init --coordinator https://your-coordinator.example.workers.dev

See Self-Hosting to run your own coordinator for free on Cloudflare.

Create a task and claim some paths

agentsync task create "Add password reset flow"
agentsync checkout AG-001
agentsync claim "src/auth/**"

If another actor already holds an overlapping claim, claim is denied (exit code 3) with the conflicting actor and a suggested wait or rebase — instead of finding out at merge time.

Check the landscape

agentsync status

Shows active tasks, active claims (actor, paths, lease remaining), stale branches, and work marked ready.

agentsync conflicts      # predict conflicts across active branches
agentsync merge-plan     # recommend a safe merge order

Commit and land your work

agentsync commit -m "feat: add password reset flow"
agentsync ready
git push

commit appends an Agent / Task / Base-SHA / Claimed-Paths trailer to the message and refuses to commit over a path another actor holds live. The installed pre-push hook verifies the same invariant against the coordinator before the push lands.

Next steps

• Read Concepts for how actors, tasks, and claims fit together.
• See the full CLI Reference.
• Read the Protocol for the invariants and config.yaml schema.