diffrat

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

The goal: every changed line on a retained branch carries rationale — an answer, an exemption, or an explicit debt record. Coverage is measured, never enforced — check/status report what is unexplained; diffrat show answers from the records 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
# ...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 sync origin brings the store — records live on their own ref, which the CLI moves itself, so nothing comes down on git clone. The remote is a required argument; diffrat never picks one for you.

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            # freezes the window; prints any lines left uncovered

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, asking why, feature branches, rebasing, backfilling history, hotfix debt, where the records live) and one reference page per command. Every example there is real, generated output from the released binary.

License

Apache-2.0