CLI Reference

Invocation

claims <command> [options]

Package: @remotehostai/claims. Bin: claims.

Global behavior:

Every command reads .claims/config.yaml from the repo root (or the nearest ancestor).
By default commands run in local mode: a lock-backed arbiter on this machine arbitrates claims and enforces the land gate for every branch, worktree and clone of the repo here. Commands print a one-line banner on stderr: local mode: claims are enforced on this machine only (sign in to Remotehost Claims Cloud to coordinate across machines). With the @remotehostai/claims-cloud package installed and claims login done, the same commands run against Remotehost Claims Cloud (cloud mode) and the banner goes away.
Exit codes: 0 success, 1 generic error, 2 usage error, 3 conflict/denied (a claim or land was refused), 4 not initialized (no .claims/).
Global options: --as <actor_id> to act as a specific actor, -C <dir> to run against another directory, -q to suppress the local-mode banner (it goes to stderr, so --json output on stdout stays clean either way).

Standalone use has no account. The actor id is resolved, in order, from --as, the CLAIMS_ACTOR environment variable, an agent session id exposed by the host runtime (CLAIMS_SESSION_ID, or CLAUDE_CODE_SESSION_ID which Claude Code sets for its hooks, Bash-tool commands and MCP servers), git config user.name (slugified), then the OS username. A session-derived actor looks like claude-6f1c2a3b; every process of that session resolves the same one, so an agent's hook checks, shell commands and MCP tool calls agree on who it is. CLAIMS_ACTOR_KIND (agent | human | human+agent) and CLAIMS_AGENT_VENDOR enrich the record; a Claude Code, Codex, or Cursor session is detected as an agent automatically.

Where state lives

.claims/config.yaml and .claims/tasks/ are committed and travel with the repo. The live claim mirror, the event log, and mutable task fields (status, base SHA, assignee) are also kept in .git/claims/, which every branch and every linked worktree of a clone shares. That is what keeps claims visible across git switch and across sibling worktrees on one machine. init gitignores .claims/claims/, .claims/events.log, .claims/CONTEXT.md and .claims/state/ by default; remove the first two lines from .gitignore to commit the mirror and log for audit.

In local mode the arbiter's own state (live claims, fence counter, lock) lives outside any clone, under $XDG_STATE_HOME/claims/local/<repo id>/ (default ~/.local/state/claims/; override the base with CLAIMS_HOME), keyed by the repo id so every clone of the same remote on this machine shares one arbiter. Coordination across machines is Remotehost Claims Cloud.

Environment

CLAIMS_REPO — override the repo id (defaults to owner/name from the origin remote, or the directory name with no remote). All actors must agree on it.
CLAIMS_SKIP_HOOKS=1 — makes the installed hooks stand down for one git invocation.
CLAIMS_HOME — base directory for local-mode arbiter state.
CLAIMS_CLOUD_MODULE — override where the CLI loads the cloud package from (development).

Commands

`claims init`

Initialize Remotehost Claims in the current repo.

Creates .claims/ 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.

Output: a checklist of what was created. Exit 0, or 1 if not a git repo. Commit .claims/ on the default branch afterwards so the config and task registry travel with the repo.

`claims 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. claims task list lists every task with its status and branch.

`claims 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 (edits under .claims/ never count as dirt).
Records the base_sha (current default_branch head) onto the task, sets it active, and assigns it to you if unassigned. Re-running switches to the existing branch.

Output: the branch checked out and its base SHA.

`claims claim <glob>...`

Claim paths for the current task and actor.

Requests a grant from the arbiter (local or cloud). On grant, writes the mirror to claims/<actor>.json with the fence_token and lease_expires_at, and appends a claim event.
exclusive_paths overlaps are denied; shared_paths overlaps are allowed with a warning.
Needs a task bound to the branch, except for agent sessions (and --ad-hoc), which claim on the current branch under the task id ad-hoc.

Repeated claims on the same task accumulate paths and refresh the lease.

Options: --intent write|read (default write), --ttl <duration> to override claims.lease_ttl, --task <task_id> to claim for a task other than the current branch's, --ad-hoc to claim on the current branch with no task.

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

`claims status`

Show the live landscape for this repo.

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

Options: --json for the full landscape (tasks, claims, branch states, conflicts, merge plan).

Output: a compact table.

`claims conflicts`

Predict conflicts across active branches.

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

Only task branches with a recorded base SHA (i.e. created by checkout) are analysed, and changes under .claims/ are ignored.

Options: --strict, --json.

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.

`claims 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.

`claims ready [task_id]`

Mark a task ready for review.

Sets the task status: ready, appends a ready event. This is recorded in the repo's task registry; it is not an arbiter operation.

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

`claims 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.

Options: -a, --all to stage modified tracked files first, --task <task_id> to attribute a different task, --no-footer to skip the trailer (only if require_agent_footer is false).

`claims push`

Push the current branch.

Runs the land-gate check first (verify-land against the arbiter), then git push, setting the upstream on a first push. A push that violates a live claim, or that carries a fence token superseded by a later grant on the same path, is rejected (exit 3).

Options: --remote <name> (default origin), -u to force setting the upstream, --force (uses --force-with-lease).

`claims 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.

claims check-commit [file...] — used by pre-commit (defaults to the staged files). Exit 3 blocks the commit.
claims check-push — used by pre-push; reads the refs git passes on stdin and calls verify-land. Exit 3 blocks the push.

A pre-existing hook is backed up to <hook>.claims-backup and still runs first.

The hooks locate the CLI in order: $CLAIMS_BIN, the absolute path recorded at init time, then claims on PATH. If none of them resolve and the repo still has .claims/, the hook blocks with an explanation rather than passing the commit through unchecked — a claim gate that silently stops enforcing is worse than one that was never installed. CLAIMS_SKIP_HOOKS=1 is the deliberate bypass, and a repo without .claims/ is never blocked.

Agent integrations

The guarantee never depends on an agent cooperating (the git hooks and the land gate see to that), but an agent runtime that is wired in gets awareness and enforcement at edit time instead of at commit time.

`claims integrate`

Detect the agent runtimes installed on this machine and register the Remotehost Claims MCP server with each of them. This is the one command to run per machine; claims init already wires the runtimes whose config lives inside the repo.

Known runtimes: claude-code, cursor, vscode, windsurf, gemini-cli, codex. Each is a row in a table of config locations — where the server list lives and how it is keyed — so support is data, not code. Registration is surgical: other servers and unrelated settings in those files are left exactly as they were, and re-running is idempotent.

Options: --all to wire every known runtime rather than only the detected ones, --remove to undo. Sub-commands: integrate list shows what is known and what was detected here, integrate mcp <id...> wires named runtimes only.

When Claude Code is among the targets it additionally gets the lifecycle hooks below, since it can enforce at edit time rather than at commit time.

Every command and config written here records an absolute path back to this CLI, so the integration survives an editor, container or CI runner whose PATH has no claims in it.

`claims integrate claude-code`

Install Remotehost Claims into Claude Code's project settings (.claude/settings.json; --global for ~/.claude/settings.json). Adds three hooks, all invoking this CLI by absolute path with hook claude-code:

SessionStart — injects the live landscape (CONTEXT.md) plus the session's actor id into the model's context.
PreToolUse on Edit|Write|MultiEdit|NotebookEdit — blocks the edit (exit 2, with the holder named) if the file is under another actor's live claim; otherwise claims the file for this session on the spot, refreshing the lease on every subsequent edit.
SessionEnd — releases the session's claims.

Each Claude Code session is its own actor (claude-<session>); a human who launches Claude Code with CLAIMS_ACTOR set keeps that identity instead, and their claims are not auto-released. The hooks are a no-op in repos without .claims/, so installing globally is safe.

Options: --mcp to also register the MCP server in .mcp.json, --remove to uninstall exactly what was added. Existing hooks and settings are preserved; re-running is idempotent.

`claims mcp`

A stdio MCP server for any MCP-capable agent. Exposes the resource claims://context (the landscape as markdown) and the tools claims_status, claims_claim, claims_release and claims_conflicts. Register it with claims integrate (every detected runtime at once), claims integrate mcp <id> (one), or by hand. It resolves the actor the same way the CLI does.

claims skills manage [dir] — scan the workspace and author/refresh skill files once (--agent claude-code codex to restrict; --watch to keep running).
claims skills watch [dir] — run continuously, re-syncing as files change.
claims skills status [dir] — show the managed skills.

claims manage and claims watch remain available at the top level, and a bare claims with no subcommand opens the live skills dashboard.