# casebook

> casebook records a decision for every repo, pull request, issue, branch and
> worktree a developer owns on GitHub and across their clones, in a private git
> repo they own (casebook-data). It observes GitHub (through gh) and the local
> clones, and surfaces only what needs attention: new, due, drifted and
> conflicting items, and policy hits. A local page (`casebook serve`) is the
> workbench: Attention, Rules and To apply, with an agent panel where a pi or
> Claude Code session works alongside through an MCP channel
> (`casebook channel`). Three rules hold: the user decides (the agent has no
> decide tool); standing rules propose and never decide; nothing outward
> happens without a plan the user approved, checked against the world before
> and after every step. casebook never calls a model. Go binary, built in the
> tackle monorepo, MIT.

Site: https://casebook.tools
Install: curl -fsSL https://casebook.tools/install.sh | sh  (macOS/Linux, arm64 & amd64; downloads from https://tackle.tools/dl/casebook/, checksum-verified, installs to ~/.local/bin)
Guide: https://casebook.tools/guide/  (a first triage, end to end)
Docs: https://casebook.tools/docs/  (install, every command, casebook serve, configuration, paths, keyboard)
Agent: https://casebook.tools/agent/  (the channel, delivery queue, tools, pi-casebook, Claude Code setup)
Rules: https://casebook.tools/rules/  (rule file, fields, operators, until forms, dispositions per kind)
Apply: https://casebook.tools/apply/  (plans, lanes, preconditions, confirmations, restore records, verification, pause, undo)
Format: https://casebook.tools/format/  (the casebook-data repository, file by file)
Source: https://github.com/schuettc/tackle/tree/main/cmd/casebook
Contact: court@subaud.io

## Setup

- `casebook init [<remote>] [--no-create] [--machine M] [--user U] [--root DIR]...`:
  writes ~/.config/casebook/config.toml and clones the casebook repo to
  ~/.local/share/casebook/repo. With no remote it uses
  `<gh login>/casebook-data`, creating it PRIVATE when missing; a public repo is
  refused. Roots default to ~/GitHub plus ~/dotfiles.
- `casebook hooks install|uninstall|status|adopt [<repo>|--all]|release [<repo>|--all] [--json]`:
  global git hook shims that journal git activity and chain to each repo's own
  hooks; `adopt` covers repos with a local core.hooksPath.
- kempt (macOS): `kempt apply -manifest https://raw.githubusercontent.com/schuettc/tackle/main/cmd/casebook/kempt.toml -packages casebook`
  installs the binary, the Claude Code hooks (PostToolUse record, SessionStart
  brief, Stop settled), the channel in ~/.claude.json and
  ~/.pi/agent/channels.json, and a launchd sync every 30 minutes.
- pi: `pi install npm:pi-casebook` (journals git/gh calls with the session id,
  briefs the first turn, background `casebook sync --no-github`, reports
  settled turns). The channel itself needs channels.tools in pi.

## Commands

- `casebook sync [--no-github] [--no-push] [--json]`: record, observe, rebuild
  the views, commit and push.
- `casebook attention [--kind K] [--repo owner/name] [--json]`: what needs you.
- `casebook show <key> [--json]`, `casebook history <key> [--json]`.
- `casebook doctor [--json]`: config, repo, gh, hooks, owner reachability.
- `casebook serve [--no-open] [--port N] [--stop]`: open the page, starting the
  one-per-machine server (127.0.0.1 only, per-start token) when needed. Any
  agent tool call also starts it; it stops after 8 hours with no traffic.
- `casebook decide <key> <disposition> [--until C] [--note N] [--by WHO] [--no-push]`,
  `casebook decide --from <file|->`: one commit per decision, pushed at once.
- `casebook triage [--kind K] [--repo R] [--out FILE]`: write a worksheet for
  `decide --from`.
- `casebook validate`: check decision files and policy.toml.
- Plumbing: `casebook channel` (MCP over stdio), `casebook settled --session ID
  [--shown IDS] | --harness claude`, `casebook brief [--cwd DIR] [--max N]`,
  `casebook record --harness claude|pi`, `casebook hook <name>`.
- Built-ins: `help`, `man`, `commands --json`, `version`, `update`.

Item keys: `repo:owner/name`, `pr:owner/name#N`, `issue:owner/name#N`,
`branch:owner/name@branch`, `worktree:machine:/abs/path`.

## Decisions

- Dispositions: keep archive close delete merge wait watch ignore. Per kind:
  repo keep archive delete wait watch ignore; pr keep close merge wait watch
  ignore; issue keep close wait watch ignore; branch keep delete wait watch
  ignore; worktree keep delete wait ignore. wait and watch need `until`.
- `until`: `date(YYYY-MM-DD)`, `merged(<pr key>)`, `closed(<pr|issue key>)`,
  `inactive(<n>h|<n>d|<n>w)`, `released(<repo key>)`.
- Status (computed): new, to-apply, waiting, due, done, drift, conflict.
  Attention = new, due, drift, conflict, plus policy hits (outgoing-stale,
  incoming-no-reply, dormant, unpushed; thresholds in policy.toml).

## The agent

- Tools: casebook_status, casebook_open, casebook_attention, casebook_show,
  casebook_history, casebook_propose, casebook_evidence, casebook_rule_draft,
  casebook_progress, casebook_reply, casebook_job_step, casebook_job_ask. There
  is no decide tool.
- Delivery is turn-aware: one delivery in flight per session; messages sent
  while the agent works are queued and arrive together at the end of its turn.
  The turn's end comes from pi-casebook (pi) or the Stop hook running
  `casebook settled --harness claude` (Claude Code).
- Message states: queued, delivered, received, working, answered, declined,
  failed, unanswered, interrupted.
- Claude Code launch: `claude --dangerously-load-development-channels server:casebook`.

## Rules

- `rules/<id>.toml` in casebook-data: `[[match]]` conditions (all must hold), a
  `[propose]` decision, optional `[[exclude]]` keys. Status draft or active.
- Fields: kind, repo, owner, relation, status, direction, author, bot, title,
  label, age, pushed, updated, landed, landed-how, gone-upstream, unpushed,
  dirty, worktree, archived, fork, open-prs, open-issues, has-decision,
  policy-hit.
- Operators: is, is-not, in, not-in (enum/text), matches (title only),
  older-than/newer-than (durations), gt/gte/lt/lte (counts).
- Rules only propose, only for undecided items, and never re-propose an item
  the user rejected unless the rule is edited. Only the user activates a rule.

## Apply

- Plans show the exact command per step; refused from an observation older than
  one sync interval. Each machine applies its own local steps; remote and
  GitHub steps run once.
- casebook lane: branch-delete-local, branch-delete-remote, worktree-remove.
  Agent lane: repo-archive, repo-delete, pr-close, pr-merge, issue-close.
- Preconditions re-checked live before each step; a restore record is committed
  to `restores/<date>.tsv` before each destructive casebook-lane step; a step is
  verified only by a fresh observation. Public text waits for the user's
  confirmation. Pause and resume a job; undo a verified step with an automatic
  restore.

## The family

- https://galley.tools: document review for agent-driven development
- https://muster.tools: local multi-agent coordination bus
- https://channels.tools: reach a running pi session through its channels
- https://hail.tools: reach a running pi session from your phone
- https://kempt.tools: declarative machine setup you can read before you run
- https://tackle.tools: small command-line tools for your terminal
- https://muda.tools: the fleet checker and auditor
- https://subaud.tools: the family landing page