Skip to content
WHY

Changelog

What changed in each release of WHY, newest first. This page is rendered from CHANGELOG.md in the repository, which follows Keep a Changelog and Semantic Versioning.

0.2.0

Release on GitHub

Session context: WHY now sees what Claude Code and Codex did in each worktree, turn by turn, and shows which agent turns explain each changed file. Every piece of it is labelled by how well it is backed: Observed (the harness recorded it), Declared (the agent’s own words) or Unknown (not enough evidence). Linux only, as before.

Added

  • Agent hooks, installed with your consent. A new Agent hooks dialog (top bar, command palette, or the empty session list) adds WHY’s hook to your user-level Claude Code (~/.claude/settings.json) and Codex (~/.codex/hooks.json) config. You see the exact diff first, and nothing is written until you confirm. WHY edits only its own lines (the rest of the file stays byte for byte), refuses symlinked, invalid or foreign-owned files, and never touches project-level config. Uninstall restores your original file exactly when you have not edited it since, and otherwise removes only WHY’s entries. Codex asks you to approve a new hook in its own /hooks screen; WHY never bypasses that, and it respects managed (enterprise) policy.
  • A fail-open hook and a local collector. The why-hook binary ships with the app. Agents run it on every event; it forwards the event over a local Unix socket and always exits 0 within a short timeout, so a slow, closed or broken WHY can never stall or fail your agent. Events made while WHY is closed are spooled on disk and arrive when it starts. Only repositories you registered in WHY are captured; everything else is dropped by the hook itself.
  • Claude Code and Codex adapters. Hook payloads become one event model: prompts, tool calls paired start-to-finish by id, edits with the files they touched (Claude Write/Edit, Codex apply_patch), shell commands, test runs, subagents. A tool call that started but never reported a result is shown as unknown, never as success. A Claude edit the harness rejected is kept as a failed attempt.
  • Session timeline in the inspector. Each worktree lists its agent sessions (harness, model, task, status, turn count); a session opens as a virtualized timeline of turns and events that updates live. Selecting a file highlights the turns that touched it and the other way round.
  • Which turns explain each changed file. The changed-files list marks each file as explained by one or more agent turns, as Agent tried, not applied, or as No captured agent edit (WHY never guesses who made such a change: a human, a shell command or a lost event all look the same). A worktree also lists the turns that ran shell commands there, as leads, because what a shell command changed is only known to git. Attribution is never made by time.
  • “Why?” on demand. Each turn and tool call can show what the agent said it was doing, labelled Declared. WHY reads it from the harness’s own transcript only when you open it, never copies it into its database, and tells you plainly when the transcript is gone or unreadable.
  • Recovered Codex outcomes. Codex hooks carry no exit code, so shell commands start as unknown. When you open a Codex session WHY reads the exit code from the structured record in Codex’s own session log and shows, for example, failed · exit 3 · from rollout (Observed). It never infers an outcome from command output.
  • Dev builds stay apart from the installed app. A pnpm dev run uses its own data directory, socket, spool and hook binary, so developing WHY cannot disturb the copy you use.

Changed

  • pnpm lint also checks formatting with Prettier. The build (pnpm build) bundles why-hook.

Known limitations

  • Linux only, unsigned builds, no auto-update (unchanged). Needs Git 2.45.1 or newer.
  • File-level attribution only. A file explained by an agent turn may still hold changes WHY did not see; line-level provenance is planned for v0.3.
  • Codex hook approval cannot be confirmed by WHY: it cannot read Codex’s trust store, so the dialog keeps reminding you to approve the hook in /hooks.
  • Long Claude transcripts are read from the start up to a budget (about 16 MiB), so “Why?” for a tool call late in a very long session may come back empty and marked as truncated.
  • A config directory inside a git worktree is refused (for example a $HOME that is itself a git repository), so hooks cannot be installed there.
  • Session context was tested against Claude Code 2.1.322 and Codex 0.170.0. Newer versions are read, but WHY says when a transcript’s version is one it has not checked, and recovers no Codex exit codes from an unchecked version.

0.1.0

Release on GitHub

First release: a read-only desktop viewer that shows the live diff of every repository and git worktree your coding agents are working in. Linux only for now (AppImage and .deb).

Added

  • Repositories and worktrees. Add a repository with the native folder picker (or the command palette, or a) and WHY lists all of its linked git worktrees. Worktrees are labelled by branch, show a status dot that pulses when something changes, group clean ones under “N clean”, and can be filtered with /. A worktree git cannot read is listed with its error instead of breaking the list, and worktrees an agent adds or removes show up without a restart. Removing a repository only forgets it in WHY; nothing on disk is touched.
  • Three diff modes per worktree. Vs base (everything since the branch left its base branch), Uncommitted (working tree against HEAD) and Staged (the index against HEAD). New untracked files show up as additions. Vs base falls back to Uncommitted for a worktree that has no base.
  • Automatic base detection, with an override. The base is the merge-base with the best candidate among origin/HEAD, origin/main, origin/master, main and master: the one the branch is the fewest commits ahead of, so work already merged into a local main is not shown as the agent’s. You can pick another base per worktree from a popover that suggests branches and validates your input; the choice is remembered.
  • Monaco diff view. A read-only, self-hosted Monaco editor (no CDN, no network) with split and unified layouts, keyboard navigation across files and hunks, and previews for non-text changes.
  • Live updates. WHY watches your worktrees (native file events, with a polling fallback). When an agent edits, stages or commits, the file list, change counts and the open diff refresh in place without losing your scroll position, and changed rows flash briefly.
  • Keyboard and command palette. j/k for files, [/] for worktrees, 1/2/3 for the diff modes, i for the inspector, Ctrl+K (⌘K) for the palette that jumps to repositories, worktrees and files, and ? for the shortcut list.
  • Editor settings. Font, font size, line height, ligatures, whitespace rendering and theme (WHY Dark and a Tokyo-Night-inspired dark theme).
  • Persistence. Registered repositories and base overrides are stored in a local SQLite database in the app data directory, and panel layout is restored on launch. If the database cannot be opened, WHY runs on a temporary in-memory store and says so in a banner.
  • Polish. First-run onboarding, resizable panels, and short transitions that respect prefers-reduced-motion.

Security

WHY is a passive observer: it runs git against repositories agents are using and must never disturb them.

  • Read-only and offline: WHY never runs a command that writes to a repository or touches the network, and it keeps partial clones from downloading objects on demand (GIT_NO_LAZY_FETCH=1).
  • All git runs through one runner: argument vectors (never a shell), a global cap on concurrent processes, and a per-call timeout.
  • It does not take locks an agent needs: GIT_OPTIONAL_LOCKS=0 for git status, and diff commands never refresh (rewrite) the index.
  • A repository’s own configuration is treated as untrusted: core.fsmonitor is forced off, and diffs run with --no-ext-diff --no-textconv, so merely looking at a repo does not run programs it names.
  • Working-tree files are opened without following symlinks.
  • The webview has no filesystem or dialog permissions; the folder picker is a command in the Rust core that returns only the chosen path.
  • Git filter drivers need your approval. A repository’s own config can define filter drivers (filter.<name>.clean or process, picked by .gitattributes) that git runs while it reads files, so merely reading a repository could run a program an agent wrote there. Before every read WHY checks the worktree’s filter configuration and refuses to read it until you choose “Trust and continue” in a panel that lists each program, its full command and where it is defined. Trust is stored per driver as a fingerprint, so a new or edited driver is asked about again; you can stop trusting a repository later. Drivers from your own git config (for example git-lfs) are allowed without asking.
  • The legacy GIT_CONFIG variable is removed from every git call, git status no longer descends into dirty submodules (their own filters would run), and WHY re-reads a repository when its git config or info/attributes changes.

Known limitations

  • Linux only. The author develops and tests on Linux, and the release ships only an AppImage and a .deb. macOS and Windows are untested and have no builds.
  • Git 2.45.1 or newer is required. Older versions cannot reliably honour GIT_NO_LAZY_FETCH, so WHY reports an error instead of reading the repository. Some current distributions ship an older git (for example Ubuntu 22.04 and 24.04, and Debian 12).
  • The “Why” inspector is a placeholder. Session context, provenance and the reasons behind each change arrive in v0.2 and later; v0.1 is the live diff only.
  • The filter-driver guard has limits. A process that can write a repository’s git config while WHY is open can still race the check, and trust covers the configured command string (a command that points at a file inside the repository trusts whatever that file later contains). See SECURITY.md for these and the other limits.
  • Unsigned builds. The release assets are not code-signed and WHY has no auto-update. Check the download against SHA256SUMS.