checkout or db-migration. One session holds it at a time. A session that tries to take a claim another session holds is refused, and told who holds it and until when.
Claims are advisory. They coordinate the sessions that check them, but they don’t lock files, block commands or sandbox anything. Agents use claims through r5dctl in their shell, and you can use them from your terminal too.
Take, check, renew and release
--status shows one topic, and session claims lists every claim on the branch. Both include expired and released claims, marked as such. Each entry shows the holder, the branch the holder works on, the claim’s generation and its expiry. --json prints the same as structured data.
A topic is free text of up to 120 characters, and a note up to 500. Write the note for the session that will be refused: what you are doing and when you expect to finish. The note stays with the claim while you hold it: a renewal keeps it, and taking the topic again with a new --note replaces it. When the topic is taken anew, by another session or after a release or expiry, the claim has the new holder’s note, or none.
The acting session. r5dctl acts as the session -s SESSION_ID names, else as R5D_SESSION_ID. An agent’s shell sets R5D_SESSION_ID to that agent’s session, so the commands above work as written there; an agent can name another session with -s, as you can. From your terminal, choose the session with -s SESSION_ID, or set R5D_SESSION_ID. It must be one of your sessions. A claim belongs to that session, not to your account.
Expiry, renewal and generations
A claim lasts for its--ttl, written as whole seconds (--ttl 7200) or with a suffix (90s, 30m or 2h). For example, 7200, 7200s, 120m and 2h all mean two hours. The CLI accepts values from 1 to 86400 seconds (24 hours); values below 60 seconds count as one minute. Without --ttl, a claim lasts 30 minutes. A renewal restarts the claim’s lifetime from now: its own --ttl, or 30 minutes again without one, even if the claim was taken for longer. Renew before the claim expires, passing the same --ttl for longer work.
Once a claim has expired, any session can take it. --renew on an expired claim fails with expired; take the claim again instead. Stopping a session does not release its claims; they last until they expire. To end a stopped session’s claim sooner, release it yourself as that session: r5dctl -s SESSION_ID session claim TOPIC --release, adding -p and --branch for a claim on another branch. A deleted session’s claims last until they expire.
Each time a topic is taken anew (by another session, or again after a release or expiry), its generation increases. --renew and --release only act on the generation this session holds. A late release from an earlier holder therefore cannot end a newer claim. r5dctl looks up the generation itself; pass --generation N only to tie the command to a generation you observed.
--release succeeds when this session holds the claim or was the last to hold it, and when the topic has never been claimed on the branch (for checkout, see the implicit hold below). It fails when another session holds the topic or was the last to hold it.
Wait for a claim
Add--notify when taking a claim. If another session holds it, the call still fails, and it also registers this session to be woken when the claim frees up:
- when the claim is released or expires;
- for an implicit
checkouthold, when every session native to that branch is idle.
wait tool, which ends with the wake reason claim_released. If the agent is busy instead, it reads the notice at its next step; an idle session starts a new run. Either way it must take the claim again. The claim is not reserved for it, and another waiting session may get it first. A registration wakes its session once. It lasts at most 24 hours, and ends when the session takes the claim.
An agent runs only with its session’s own connected worker. When you register a session that has none from your terminal (-s SESSION_ID), the output says so: the notice still reaches the session’s transcript when the claim frees up, but its agent reads it only once you select a worker for it (r5dctl session set-worker SESSION_ID --worker WORKER), which continues the session. A session whose worker is offline gets the notice when the worker reconnects.
The checkout topic
checkout is reserved for writing tracked files in a branch’s checkout.
On your own branch, the hold is implicit. A session native to a branch holds checkout there without claiming it until the session is idle: while its agent runs, while input waits to start its next run, and while it is suspended in a wait, for a subagent, a command or a claim. --status lists that hold as (native, running), or queued, waiting or paused (a run paused for recovery), and held until the holder is idle (implicit). A session that is idle, stopped or waiting for your answer holds nothing. Nothing is stored for the hold, so it cannot be renewed or released. Without an explicit claim of its own, --renew and --release answer held_implicitly and exit non-zero.
A session may still claim checkout on its own branch explicitly, to leave a note or to hold it once the session is idle, for example while a command it started keeps running. --status then lists both entries, the explicit claim first. --renew and --release act on the explicit claim, like any other claim.
In another checkout, claim it first. Before writing in another branch’s or project’s checkout, for example one referenced as @project/branch, claim checkout there. Hold it until the write is done, then release it:
-p (a project slug or ID) and --branch go together. They name a branch of one of your projects instead of the session’s own branch. While a session native to that branch is busy, the claim is refused and names it. Message that session with r5dctl session prompt, which also ends its wait, or claim with --notify and wait. Don’t wait for a session that is waiting for you, such as the session that started yours as a subagent: it keeps its hold while it waits, so message it instead.
Once you hold the claim, taking it again renews it, like --renew, even while a session native to that branch has become busy. Both answers then name that session on a Native session busy: line, since it may write in the same checkout.
Claiming checkout does not fence or lock the checkout on any worker. It stops no command from writing there, and the claim’s output says so on a Fence: line. Sessions native to that branch are told about it instead: while your claim lasts, session start, session prompt and session status for any of them print a Warning: line naming your session and its note, and their agents’ instructions name your claim at every step. They are asked to coordinate with you before writing tracked files, so write a note that says what you are changing.
Shared host resources
A claim covers one project branch. Two sessions on different branches that claim the same topic name do not exclude each other. To share something on a worker host, such as a port, a Docker daemon or a scratch directory:- Agree on one explicit scope (
-p PROJECT --branch BRANCH) that every participating session uses. - Use a topic that names the worker, for example
build-host:port-4193for port 4193 on the workerbuild-host. - Hold the claim, renewing it, until cleanup is finished.
Outcomes
Taking, renewing and releasing a claim print the outcome in words on anOutcome: line; --json gives its code in the outcome field. Every outcome that shows a claim names its holder the way session claims does: the session’s ID, its name, and (native) or (foreign: native to branch …). Only acquired, renewed and released exit zero, as does missing for --release.