git-why launched this week as an open protocol that captures and stores AI coding assistant reasoning traces alongside source code in git repositories. Created by developer Pierre, the tool addresses a real gap: when developers use AI assistants like Claude Code, Cursor, or Copilot, the conversations and decisions that shaped the code vanish once the session ends. Git blame tells you who changed a line and when. git-why tells you why they changed it.
The protocol works by mirroring your project structure in a .why/ directory. Each source file gets a corresponding Markdown file containing reasoning traces: the original prompt and a summary of what changed, plus any alternatives that came up. A pre-commit hook automatically detects active AI sessions and writes these traces when you commit.
The format is plain Markdown, append-only, and merge-friendly using git's union merge strategy. You can read traces with cat, grep, or the included CLI.
What makes this practical is the tool-agnostic design. Alice can use Claude Code while Bob uses Cursor, and their reasoning ends up in the same consistent format managing multiple coding agents. Manual annotations work too. The protocol excludes sensitive data like API keys and tokens by default, with customizable .whyignore patterns.
Adding support for a new AI tool requires just one shell script with five functions.
AI-assisted coding is becoming standard, but the context around those changes keeps disappearing. Teammates reviewing code weeks later see commit messages like "Add retry to auth" but not that the developer considered and rejected a circuit breaker approach. Git-why makes that reasoning persistent, versioned, and searchable.
Right now the project has rough edges. It's at v0.1.0, the union merge strategy can conflict in busy repos, and there's no UI beyond the CLI. But the RFC and reference implementation are available on GitHub for anyone who wants to kick the tires.