How-to

Point at a graph

--dir DIR, else CLAIMDAG_DIR, else $XDG_RUNTIME_DIR/claimdag. With no runtime directory it is $XDG_STATE_HOME/claimdag, else ~/.local/state/claimdag, else /tmp/claimdag-UID. Each default belongs to one user: claimdag makes it with mode 0700 and refuses it when another user owns it. A directory named by CLAIMDAG_DIR or --dir is used as given, so a team can share one on purpose. The working directory is never used, so a worker in the wrong directory does not invent a second graph. A reader that finds no graph says so rather than answering “nothing claimable”.

Pick the next node

claimdag list shows live work newest first. The ready nodes are the ones to claim; among them, the one with the longest chain of dependents below it frees the most work. The Model Context Protocol (MCP) tool claimdag_ready returns them in that order with waiting_below on each row, the critical-path rule of Hu (doi:10.1287/opre.9.6.841) and Graham (doi:10.1137/0117039).

Take work with several workers at once

$ claimdag claim-next --assignee $me --role verifier
f7b7df44c9323a9e2a4aee09c5c74725  gen=2

Several workers can read the ready list at once and claim its head. All but one are refused. claim-next chooses and claims under the directory lock, so the next worker in sees the claim.

Claim from a tracker id

claimdag knows nothing about tickets. The seat maps a tracker id to one node and a name to one actor, so ljos claim proj-1a2b --assignee you works; see the ljos site. On its own, claimdag takes 32-hex ids only.

Fence a completion

$ gen=$(claimdag claim $id --assignee $me | sed 's/gen=//')
$ ... work ...
$ claimdag complete $id --status done --actor $me --gen $gen

Pass the generation you were given. If the node was reclaimed and taken by someone else in between, the completion is refused.

Hand back stalled claims

$ claimdag reclaim --lease 900

Every claim quiet for longer than 900 seconds returns to ready. Run it from a timer, or from the pane with one key.

Keep the list short

$ claimdag archive $id
$ claimdag list --terminal     # finished, not archived
$ claimdag list --all          # everything

Archive sets a flag; the node and its terminal status stay.

Drive the pane

$ claimdag-tui

The pane shows live work and how long each held node has been quiet. It claims and completes through the same graph calls the command line makes, and hands back every stale claim with one key. It relaxes none of the guards.

The graph is a DAG over dependencies and a forest over parents; the pane draws the forest. Bindings: c claim, d complete, a archive, u unlink, h show finished, A show archived, r reload, q quit. Colours come from the terminal. --dump prints the forest and exits.

CLAIMDAG_ACTOR pins who the pane claims as; without it the id is derived from user and host, so the same seat is the same actor across restarts. handles.json in the graph directory, or CLAIMDAG_HANDLES, maps actor ids to names a person recognises.

Serve to an agent

$ claimdag-mcp

The tools that read are claimdag_ready, claimdag_ready_balanced and claimdag_list. The rest change the graph: claimdag_claim, claimdag_claim_next, claimdag_renew, claimdag_release, claimdag_reopen, claimdag_complete and claimdag_reclaim. Two prompts sequence taking the next node under a lease and sweeping stale claims.