Get started.
Install why-diff, capture a Codex session, and ask about a change.
Install
Homebrew is the simplest route on macOS or Linux.
$ brew install prsuyal/tap/why-diffOr use the release installer. It verifies the archive checksum and places both commands in ~/.local/bin.
$ curl -fsSL https://raw.githubusercontent.com/prsuyal/why-diff/main/scripts/install.sh | shOn Windows, or if you prefer to install by hand, get an archive from GitHub Releases ↗. Put both why-diff and why-diff-hook on your PATH.
Turn on capture
To capture Codex sessions in every Git repository you use:
$ why-diff init --globalTo capture only in the current Git repository:
$ why-diff initReview and trust the generated Codex hooks, then start a fresh Codex session. Run why-diff doctor inside a repository to check the setup. A warning about having no sessions yet is normal.
$ why-diff doctorExperimental agent hooks
v0.2.0 includes hooks for Claude Code, Cursor, Gemini CLI, and GitHub Copilot CLI. They pass local hook and changed-line tests but have not been checked in live sessions with those agents.
After installing, choose an agent:
$ why-diff init --agent cursor --globalUse claude, gemini, or copilot in place of cursor. The adapter setup guide ↗ covers each host and its known limits.
Ask about a change
After an agent edits code, list your recorded sessions and choose a file or line from the diff.
$ why-diff sessions$ why-diff why path/to/file.go:42why shows the request, the tool call during which the edit appeared, its patch, and any matching test result. It cannot tell you why the agent chose a particular value. Use why-diff show latest for the session timeline.
Good to know
It stays local.
Capture and ordinary queries do not contact a model provider. An explicit explain request does.
It shows its limits.
A change between tool checkpoints is strong timing evidence. It cannot prove that one tool call was the only cause.
You can turn it off.
Run why-diff disable for a repository or why-diff disable --global for user-level hooks. Captured evidence stays in your local Git repository.
Requires Git 2.42 or newer. Codex CLI 0.156.1 is the version verified end to end for automatic capture.
Command reference
Where a command accepts [session], use a full session ID, an unambiguous prefix, or latest. Omitting it selects the latest session.
Setup and health
why-diff init [--global] [--agent NAME]Add hooks to this repository or your user settings. Defaults to Codex; repeat --agent for more than one host.
why-diff doctor [--agent NAME]Check Git, hooks, installed binaries, sessions, and capture warnings.
why-diff disable [--global]Remove why-diff hooks. Captured evidence stays in Git.
Investigate
why-diff sessionsList captured sessions, newest first, with event and warning counts.
why-diff show [session]Read the event timeline, including prompts, tool calls, and results.
why-diff diff [session]See changes observed between tool checkpoints.
why-diff why <file[:line]>Find the tool interval that contains the change, with its request, patch, and evidence IDs. Add --session to narrow the search.
why-diff lineage <file:line>Follow a function, method, class, or type across captured edits and moves.
why-diff claims [session]Find fail-change-pass test sequences in the recorded evidence.
why-diff compare <session-a> <session-b>Compare prompts, changed files, and validation commands. Add --patch for checkpoint patches.
Optional model interpretation
why-diff explain <file[:line]> --dry-runShow the exact evidence packet without making a model request.
why-diff explain <file[:line]>Request a citation-checked interpretation from the configured OpenAI model.
why-diff compare <a> <b> --dry-runShow the comparison packet without making a model request.
why-diff compare <a> <b> --explainRequest a model interpretation of two attempts.
Maintenance
why-diff finalize [session]Archive an active session under a private Git ref.
why-diff index statusShow the contents of the rebuildable SQLite query index.
why-diff index rebuildRebuild that index from Git objects and canonical event logs.
why-diff completion <shell>Generate completion for bash, fish, PowerShell, or zsh.
explain and compare --explain accept --model and --timeout. Run why-diff <command> --help for every flag.