Guides

Decisions and sessions

Record why code is the way it is, and see when parallel sessions overlap.

Decision graph

bash

contextbridge decision add "Use SQLite" \
  --why "No server to run" \
  --rejected "Postgres: needs a service" \
  --requirement "Runs offline" \
  --code src/db.py:connect \
  --test tests/test_db.py \
  --consequence "Single writer"

A decision can link to a requirement, code (PATH or PATH:SYMBOL), tests and other decisions (--depends). Adding one also re-renders DECISIONS.md.

Command	Does
`graph show`	List every node.
`graph query TERM`	Find nodes containing the term, with their neighbours.
`graph trace ID`	Walk from one node to everything connected to it, grouped as requirements, decisions, code and tests.
`graph check`	Report linked files that no longer exist (STALE), decisions with no linked test or requirement (INFO).
`graph render`	Regenerate `DECISIONS.md` from `graph.json`.

Sessions

bash

contextbridge session start auth --task "Login flow" --agent claude --claim "src/auth/*"
contextbridge session list
contextbridge session finish auth

Sessions record who claimed which paths. session list reports overlapping claims between active sessions (a warning when both claims cover modified files) and sessions that depend on one still active. This is advisory only: it cannot prevent conflicts across clones or machines.