Getting Started

Install

npm i -g @remotehostai/claims

This installs the claims command.

Initialize a repo

From inside a git repository:

claims init

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

Commit .claims/ on your default branch so the config and task registry travel with the repo.

Out of the box Remotehost Claims runs in local mode: a lock-backed arbiter on this machine grants claims in a total order and enforces the land gate for every branch, worktree and clone of the repo here. That is the full guarantee for a single-machine swarm, with no server and no account.

Coordination across machines is Remotehost Claims Cloud, coming as a separate package that adds claims login; the same commands then run against the hosted arbiter, and nothing in the repo changes between the two modes (.claims/config.yaml is policy, not connection settings). Early access: https://remotehost.ai/extensions/agent-claims.

Create a task and claim some paths

claims task create "Add password reset flow"
claims checkout AG-001
claims 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

claims status

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

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

Commit and land your work

claims commit -m "feat: add password reset flow"
claims ready
claims 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. push verifies the same invariant against the coordinator before the push lands, and the installed pre-push hook does the same for a plain git push. Release your paths when you are done:

claims release

Wire up your agents

claims init already installed the git hooks, which enforce claims for every agent and every human — an agent that knows nothing about Remotehost Claims is still refused at commit time. This step is the other half: letting a cooperating agent see the claims before it edits.

claims integrate

That detects the agent runtimes installed on this machine and registers the Remotehost Claims MCP server with each, so the model gets claims_claim / claims_status tools and the live landscape as a resource. claims integrate list shows what is known and what was found; claims integrate <id> wires one; --remove undoes it.

Claude Code gets more, automatically: it also exposes lifecycle hooks, so every session starts with the landscape in context, is blocked from editing a file another actor holds (the model is told who holds it and moves on), claims each file it edits, and releases on exit. Each session is its own actor, so several sessions in parallel worktrees coordinate with no extra setup.

Every generated hook and config records an absolute path back to the CLI, so integrations keep working inside editors, containers and CI where PATH may not include claims.

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.