Git Why MCP server

Git Why

git blame tells you who changed the code. git why finds the history that explains it.

Local-first semantic + full-text search over Git history. It returns the actual commit, its author's real words, and the relevant diff. It retrieves evidence; it does not generate an explanation of its own.

Real output from mise run demo, which rebuilds a small fixture repository from bench/fixtures/demo/build.mjs and runs these two queries against it. Nothing here is hand-written, and you can reproduce it in one command.

For output against real repositories — curl, zod, redis — including a worked case where this is the wrong tool, see docs/examples.md or the recorded terminal sessions.

$ git why "that bizarre bug where reconnecting subscribed twice"

1. 7deab42  Stop duplicate subscriptions after reconnect
   2025-11-20 · Maya Chen

   Reconnecting re-ran the subscribe handler without clearing the previous
   registration, so every reconnect doubled the delivered events.

   src/net/socket.ts
   -export function connect(url) { return new Socket(url); }
   +export function connect(url) {
   +  const s = new Socket(url);
   +  s.on('reconnect', () => resubscribeOnce(s));
   +  return s;
   +}

$ git why "why do we keep the session when the refresh token is empty?"

1. f17db20  Fix infinite token-refresh loop
   2025-11-03 · Maya Chen

   Provider X can return an empty refresh token while the current access
   token remains valid. Retrying here puts clients into an infinite loop.

   src/auth/refresh.ts
    export function refresh(session, refreshToken) {
   -  if (!refreshToken) throw new InvalidTokenError();
   +  if (!refreshToken) return session;
      return exchange(refreshToken);
    }

Install

Install from npm (Node >= 22.12):

npm install -g @alliecatowo/git-why

Or with Homebrew (macOS and Linux; pulls in node):

brew install alliecatowo/tap/git-why

Or build from source:

git clone https://github.com/alliecatowo/git-why.git
cd git-why
npm ci
npm run build
npm install -g .

The package installs a git-why executable, which Git dispatches as the subcommand git why. No alias setup needed. More install paths — pinned versions, a GitHub release tarball, building from source, uninstalling — are in docs/install.md.

Use it with an agent

Two plugins ship in plugins/:

OpenCode users get opencode/ — an opencode.json with the MCP registration and an AGENTS.md fragment.

What the skill actually teaches is when not to reach for history. It tells an agent to use git log -S when it can name the symbol, because that is a case this tool measurably loses (Hit@10 0.950 against 0.350), and to use code search rather than history for the current state of the code. A skill that claims its own tool is always best makes an agent worse at its job.

Shortened. The full README is on GitHub.