diffrat

Capture the why behind code changes, store it in git-adjacent records, and make it queryable by humans and agents ("why is this code the way it is?").

The invariant: on an enforced branch, every changed line carries rationale — an answer, an exemption, or an explicit debt record. A pre-push hook gates on it; diffrat show answers from it later.

Install

go install github.com/cameron-mcateer/diff-rationale/cmd/diffrat@latest

The only runtime dependency is git. Prebuilt binaries for Linux, macOS, and Windows are on the releases page.

The VS Code extension (diffrat-<version>.vsix) is attached to each release; install it with Extensions: Install from VSIX… or code --install-extension diffrat-<version>.vsix.

Try it

cd <your-repo>
diffrat init            # writes .rationale/ schema+config (commit those),
                        #   mints the epoch, installs this clone's pre-push hook
# ...make a change, commit it...
diffrat check           # shows what still needs rationale
diffrat interview       # answer; records land on refs/rationale/records
diffrat show path.go:42 # ask why later

On any other clone: diffrat install for the hook, diffrat sync for the store — records live on their own ref, which the CLI moves itself, so nothing comes down on git clone.

Or stage the rationale without a prompt — the path an in-session agent takes while it is still making the change:

diffrat add src/cache.go:41-58,L15-33 \
  -m motivation "why this change" -m alternatives "what was rejected" \
  --author "Agent Name <agent@example.com>"
# ...`add` prints the lines still uncovered; repeat until none...
git commit -am "..."
diffrat mint            # refuses unless every changed line is covered

Working with a coding agent

agents.md is a drop-in brief for LLM coding agents: paste it into your agent instructions and the agent stages rationale for its own changes with diffrat add as it works, then diffrat mint after the commit.

Documentation

The full manual is in docs/ — workflow guides (adopting, the daily loop, feature branches, backfilling history, hotfix debt, enforcement) and one reference page per command. Every example there is real, generated output from the released binary.

License

Apache-2.0