Story claims
From 3.21.0, build-item can claim each story before it starts it, so two agents on two machines never build the same one. Claims live in DevStride or behind your own commands. Without a claims block nothing is claimed and nothing changes.
| Key | Value | Default | What it does |
|---|---|---|---|
claims |
null, { "provider": "devstride" }, or { "commands": { "claim", "heartbeat", "release", "get"?, "list"? } }; both forms take an optional expiryMinutes |
absent: no claims | provider: "devstride" uses the agent's own DevStride MCP connection; its user needs the MANAGE_AGENT_CLAIMS permission (API Keys group of its role). commands runs your own claim store: each command gets <kind> <key> and its options (claim: --purpose, --phase, --expiry, --takeover; heartbeat: --phase; release: --outcome; list: --kind), the session's identity in CLAIM_HOLDER (never on the command line), and answers with a verdict on stdout's first line (WON, LOST, OK, NOT HOLDER, ABSENT, FORBIDDEN, UNREACHABLE, ERROR) and exit 0 won or ok, 2 lost, 4 not the holder, 1 anything else. Giving both forms, an unknown provider or a missing command is a config error. |
claims.expiryMinutes |
{ "<kind>": minutes }, e.g. { "story": 240 } |
story 240, release-train 30; any other kind, the server's default |
How long a claim lives without a heartbeat. A value outside 1 to 1440 is a warning and the default stands. The release permit's own claim is not set here: it lasts release.clearance.staleMinutes. |
How the loop uses them:
- Selection. The chosen story is claimed before it moves to In Progress. A story another live agent holds is skipped for the next candidate, and the loop says who holds it. A story you named, or the one a session resumes, stops instead, naming the holder's machine and session and since when. An expired claim is taken over. Your own earlier session (after a restart or
/clear) counts as another holder: wait out the expiry, or the owner releases the claim. - While building. Each step and build phase renews the claim. A phase longer than the expiry lets the claim lapse, unless the repository's presence command renews it while the session is active; the next renewal claims it again if it is free. If another agent took the story after it lapsed, the loop stops and names that agent.
- Finishing. Completion, whether the story is Done or has landed on an integration branch or the train, releases the claim with outcome
done. A stop releases nothing itself: the claim expires, or a presence command releases it when the session ends, so a person can resume the story without a takeover. - The record. From 3.43.0 every claim names its machine and session the same way: the machine is
DEVSTRIDE_MACHINE_NAMEwhen your machine setup sets it, else the host name without.local, lower-cased with other characters turned to hyphens; the session name is Claude Code's own name for the session, elseDEVSTRIDE_SESSION. Release clearance and session presence use the same machine name. - When claims are unavailable — the server has no claim tools yet, the key lacks the permission, or DevStride cannot be reached — the loop carries on without claims and says so once per session. A claims outage never stops delivery.
- Hotfixes never claim, and a claim is a speed bump, not a lock: a person or an older plugin that never claims can still move the item.
The full contract is skills/build-item/references/story-claims.md in the plugin repository.