whyDocumentation
What whydid actually does, feature by feature — not a pitch, a reference. Everything here runs locally on your own machine; nothing described below requires whydid's own servers.
Start here
What whydid is
Undo for AI coding agents. It watches your project and records every change — whether Claude Code, Codex, Cursor or you made it — as a numbered list. Each change carries the prompt that caused it and the agent’s own explanation. When one goes wrong, you undo just that one, and keep everything else.
It is not version control. It runs alongside git (or without it) and fills a different gap: why a change happened, tied to the actual prompt that caused it, plus a safety net for the moments in between commits — the exact window where a bad AI-driven edit is hardest to undo cleanly.
The model
Checkpoints, not commits
Every state whydid records — the initial snapshot, each checkpoint, every restore and fork — is a node in a real branching graph, parented on whatever came before it. A restore doesn’t discard your current work to get there: it safety-snapshots what’s on disk right now, automatically, before touching anything, so the state you were just in is always still there as its own node.
Files are stored content-addressed and deduplicated — only a full manifest is kept periodically, with everything else stored as deltas, reconstructed exactly on demand. A 10,000-checkpoint project doesn’t mean 10,000 copies of every unchanged file.
Feature reference
Every feature, plainly explained
list, diff, undo
whydid list shows every change newest first, numbered 1, 2, 3… with the prompt behind it, a line of the agent's reply, and the files it touched. whydid diff 3 shows exactly what change 3 did. whydid undo 3 takes out only what change 3 did, even when newer changes came after it: edits made since, by any agent or by you, stay. If a newer change rewrote the very same lines, it says so and asks whether to leave that file or put it back whole; and it warns you when a newer change uses something change 3 added. --only undoes just some of its files.
bisect — find the change that broke it
whydid bisect runs your test command against past versions of the project and names the first change where it fails, with its prompt, the agent's reply and how the test failed. Each version is rebuilt in a throwaway copy with your real node_modules/.venv linked in, so your working files never move and the watcher records nothing. It binary-searches, so hundreds of changes take a handful of runs. Uses the command from Settings, or detects npm/pnpm/yarn/bun test, pytest, cargo test or go test; --good <n> starts from a change you know worked.
Sessions & write-ups
Every agent session reads as a work log: each prompt, the agent's reply, and the change it made. Undo a whole session in one step: whydid takes out the session's own edits and keeps anything made since outside it, telling you first about any overlap. Write it up as a commit message or a markdown summary for a PR or a fresh agent session. The Changes page's Since last commit view does the same for your uncommitted work.
The why, from your own agent
For every agent turn, whydid stores the prompt you typed and the agent's own closing reply, and attaches both to the change that turn produced. That's the explanation you see in list, diff, undo and why — the agent's real words, not a second AI's guess. No API key and no extra AI call.
Dashboard & AI summaries
whydid daemon start opens a local dashboard: Changes (with Undo on each), Find what broke, Sessions and Settings. Alongside the agent's own words, each change gets an AI summary (a short summary, key decisions and a risk level), written once per change by the coding agent this project uses, Claude Code or Codex, on your existing plan. Switch to an Anthropic/OpenAI key, or turn summaries off, in Settings.
Restore — full or selective
Jump back to any checkpoint's exact state. Every restore safety-snapshots your current disk first, automatically — nothing is ever silently overwritten. Selective restore lets you pull back just the files you need, leaving everything else you've built since exactly as it is.
Fork
Branch a new line of work from any past checkpoint without disturbing your current state — for trying an alternative approach without losing where you are now.
Milestones
Tag any checkpoint with a label of your own choosing — "v1 launch," "before pricing change" — so it stands out later, instead of getting buried among hundreds of routine ones.
Multi-agent session capture
Prompts and turns are captured automatically from Claude Code, and via lightweight hooks from Codex and Cursor — each turn linked to the exact checkpoint(s) it produced, so you can see which prompt caused which change.
Settings & privacy controls
See which coding agents are connected (and connect Codex/Cursor in one click), set the test command Find what broke uses, and turn AI summaries on or off — including exactly what each request may include. Everything lives in .whydid/config.json, a plain file you can read or edit.
Terminal
CLI reference
| whydid init [--agents] | Set up whydid in the current project and capture its initial state. Writes nothing outside .whydid/ unless you pass --agents, which adds Codex/Cursor hooks and agent instruction files. |
| whydid list [-n <count>] | Numbered list of recent changes, newest first, with prompt, agent reply and files. Alias: ls. |
| whydid diff [n] [files…] [--stat] | Show exactly what change n did (default: the latest), with the prompt and the agent's reply. |
| whydid undo [n] [--only <paths>] [--yes] | Undo change n (default: the latest), keeping newer edits wherever they don't overlap. Saves your current files first, so the undo can itself be undone. |
| whydid bisect [command] [--good <n>] | Find the change that made your tests fail, by testing past versions in a scratch copy. |
| whydid summary [--ai] [--markdown] | A commit message (or markdown write-up) for everything since your last commit, from your prompts and the agent's replies. --ai has your configured agent write it. |
| whydid why <file> | Show what the agent said about a file's most recent change. |
| whydid checkpoint | Record a change right now (usually automatic while the daemon runs). |
| whydid status | Show the current state, last checkpoint, and any AI budget warning. |
| whydid timeline | Every recorded state, oldest branches included. |
| whydid restore <n|id> [--only <paths>] | Put the whole project (or just some files) back to how it was at a past state. |
| whydid fork <n|id> <name> | Branch a new line of work from a past state. |
| whydid milestone <id> <label> | Tag a checkpoint as a milestone (or list all tagged ones with no arguments). |
| whydid daemon start|stop|status | Manage the local dashboard's background process. |
| whydid recap | A one-day or one-week summary of activity, risk, and test status. |
| whydid test | Run your configured test command and attach the result to the current checkpoint. |
| whydid export | Export your project's full recorded history as JSON, Markdown, or HTML. |
| whydid login <licenseKey> | Activate whydid on this machine (2 devices per license). |
| whydid logout | Deactivate this machine, freeing its device slot. |
| whydid license | Show local license status — no network call. |
| whydid reset | Stop the daemon, back up .whydid outside the project, and reinitialize — for recovering from an upgrade clash or corrupted local state. |
Compatibility
Platforms & coding agents
macOS, Linux, and Windows are all supported — not assumed to work the same way and left untested. Machine identification, OS keychain storage, and file-watching have each been checked against real platform differences rather than ported once and hoped for: Windows, for instance, names Claude Code’s session folders differently than macOS does, and locks open files in ways POSIX doesn’t — whydid accounts for both rather than assuming one platform’s behavior everywhere.
whydid requires Node.js 24+ (or 23.4+) for its built-innode:sqlitesupport. If your default node resolves to something older, the CLI detects this at startup and tells you exactly what’s installed and how to fix it, rather than failing with an unrelated error.
Coding agent support, honestly tiered:
- Claude Code — deepest integration. whydid reads Claude Code’s own local session transcripts directly, with nothing to install: each prompt and Claude’s reply land on the change they produced, and changes split exactly at prompt boundaries instead of waiting for a debounce timer.
- Codex and Cursor — hook-based.
whydid init--agentsinstalls a small, standard hook config for each (.codex/hooks.json,.cursor/hooks.json) that reports prompts and the agent’s final reply through each tool’s own supported hook interface — the same prompt-and-reply on every change, without reading any private file format. Both agents only run a project’s hooks once you approve them: in Codex, review them with/hooks(and again whenever they change); in Cursor, trust the workspace. Settings in the dashboard shows whether each agent is connected. - Any other AI coding tool, or plain manual edits — list, diff, undo, restore and fork all work identically. whydid’s file watcher doesn’t care what made the change. What you won’t get without Claude Code, Codex or Cursor is the prompt and the agent’s reply — those changes show as “edit (no prompt recorded)”.
- By default
whydid initwrites nothing into your repo besides its own self-ignoring.whydid/folder.whydid init --agentsadditionally installs the Codex/Cursor hooks and theAGENTS.md/CLAUDE.md/ Cursor rules instructions for whydid’s CONTEXT.md convention.
When something's off
Troubleshooting
A password/permission popup appeared when I ran a command
That’s your OS’s own credential store (macOS Keychain, Windows Credential Manager) asking to let whydid read your saved license — not a whydid password. It’s your own computer’s login password. Click Allow (or Always Allow) and the command continues normally.
The daemon won’t start, or I can’t reach the dashboard
If whydid’s preferred port is already taken by something else, it automatically falls back to a free one — the correct URL is always printed by whydid daemon start and whydid daemon status. If it still won’t come up, check .whydid/logs/daemon.log in your project for the real error.
Changes show up, but say “no prompt recorded”
This means the file watcher is working but session capture isn’t finding your agent’s transcript or hook events — see Platforms & agents above for which tools get this, and confirm whydid init ran in this exact project folder. For Codex or Cursor, run whydid init --agents there (hooks are per-project). This never blocks recording changes — it only means they won’t show which prompt caused them.
Something’s acting strange after an upgrade, or feels corrupted
Run whydid reset. It stops any daemon still running for the project, moves your existing local history outside the project folder (nothing is ever deleted), and reinitializes fresh. If the backup turns out fine, you can safely remove it later — the command tells you exactly where it landed.
AI summaries aren’t being generated
Check Settings → AI summaries. Automatic uses Claude Code or Codex, so one of them must be installed and signed in on this machine (run it once in a terminal); with neither, summaries simply wait. After three failed calls in a row whydid pauses them for 30 minutes rather than slow down every change. For an API provider, check that a key is set and your monthly limit (if any) hasn’t been hit. Everything else (list, diff, undo and the agent’s own explanations) works with AI off.
whydid --version shows an old version after upgrading
Usually a second, stale global install earlier on your PATH. Run which -a whydid to see every copy; if more than one shows up, remove the older one (e.g. npm uninstall -g whydid --prefix <that path>) and reinstall.
Still stuck? Email hello@whydid.dev — a real response, not a ticket queue.
Trust
Privacy
Your source, history, and snapshots stay on your machine — whydid’s own servers never receive your code. The prompts and agent replies whydid shows are read locally from your agent’s own transcript or hooks; they never leave your machine either. whydid’s servers only handle license activation, plus anonymous usage counts if you opt in (off by default). AI summaries are written by your own Claude Code or Codex (run with no tools, from an empty folder), or by your own Anthropic/OpenAI account with your own key.
You control exactly what’s sent for those calls — your prompt, the diff, both, or neither — in Settings. Unchanged source and your full repository are never sent, regardless of these settings. whydid never logs or transmits your API key itself.
No subscription
Pricing
A one-time lifetime license — $29 — yours for good. No monthly fee, no seat count, no usage meter. Unlimited projects on one license, two device activations. No API key is needed. AI summaries use a little of your own coding agent’s usage (one short call per change), and you can turn them off.
See pricing details →