Reference

Command line#

claimdag [--dir DIR] VERB

Verb	Does
`upsert [--id ID] [--kind K] [--status S] [--role R] [--parent ID] [--summary TEXT] [--actor ID]`	create (mint when `--id` is absent) or update a node
`get ID`	one node with its dependencies
`list [--terminal] [--archived] [--all] [--json]`	nodes, newest first; live work by default
`claim ID --assignee ID [--gen N]`	compare-and-swap claim; prints the new generation
`renew ID [--actor ID]`	move the lease, keep the generation
`release ID (--actor ID \| --force)`	hand one claim back before it is terminal: ready, no assignee, generation moved. `--actor` must be the holder; `--force` acts for nobody and appends a line to `forced.log`
`reopen ID [--actor ID]`	bring a terminal node back to ready, generation moved. No record of the earlier completion is kept on disk
`complete ID [--status done\|failed\|cancelled] [--summary TEXT] (--actor ID \| --force) [--gen N]`	terminal; refused when `--gen` is stale, and `done` is refused while a dependency is unfinished. `--force` acts for nobody and appends a line to `forced.log`
`reclaim [--lease SECS]`	hand back every claim quiet longer than the lease
`link PARENT CHILD` / `unlink PARENT CHILD`	a hard dependency
`archive ID` / `unarchive ID`	hide or show a terminal node
`ready [--role R] [--assignee ID] [--slack N] [--balanced] [--json]`	ready nodes ordered by list scheduling or balanced P2C dispersion
`claim-next --assignee ID [--role R] [--slack N]`	atomically select and claim the best ready node with role affinity and P2C dispersion

Ids are 32 lowercase hex characters (xxHash3-128). The zero id means unset.

Statuses#

todo, ready, claimed, done, failed, cancelled. ready is derived: a todo node whose every dependency is terminal. A claim requires ready. One live claim per assignee.

Kinds and roles#

Kinds: task and the closed set the schema names. Roles: unset and the closed set the schema names. Summary is the one open text field.

The snapshot#

work.bin in the graph directory: an unpacked Cap’n Proto message, mapped read-only by readers and rewritten whole by the one mutating process. A directory with no file is an empty graph to a writer and “no graph here” to a reader.

Environment#

Variable	Meaning
`CLAIMDAG_DIR`	the graph directory; else `$XDG_RUNTIME_DIR/claimdag`, then `$XDG_STATE_HOME/claimdag`, `~/.local/state/claimdag`, `/tmp/claimdag-UID`

Crates#

Crate	Carries
`claimdag`	the graph, ids, leases, critical path, the snapshot
`claimdag-cli`	`claimdag`
`claimdag-tui`	the pane, on icedtea
`claimdag-mcp`	the Model Context Protocol (MCP) surface