Performs semantic and full-text search over Git history to find commits that explain the reasoning behind code changes.
Also known as alliecatowo/git-why, git-why, @alliecatowo/git-why
- Stars
- 0
- Tools
- 2
- Downloads, 30 days
- 283
- Latest version
- 0.2.0
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is Git Why MCP?
Git Why performs semantic and full-text search over Git history to find commits that explain the reasoning behind code changes. It exposes 2 tools, such as git_why_search, git_why_status.
Summary generated from the project's README
About Git Why MCP server
Finding the reasoning behind code changes by searching through Git history is what Git Why enables for developers. Unlike standard Git tools that require exact keywords, this server uses semantic and full-text search to match the intent of a problem described in natural language to the actual commit, author comments, and relevant diffs. It is designed for local use, indexing a repository's history into a local directory to provide evidence-based answers rather than generating synthetic explanations.
Users can run the server via npx or as a Git subcommand after installation. It requires Node.js version 22.12 or higher and automatically downloads a small embedding model for its first run. For improved performance on large repositories, a daemon can be started to keep the index and model in memory. The server provides specific skills for AI agents, helping them decide when to use semantic history search versus standard pickaxe searches or current code search tools.
What you can do with it
- 1Locate reasoning for obscure bugsAsk an AI to find the specific commit that addressed a bug when you only remember the symptoms in plain English.
- 2Search history without exact keywordsFind historical context for a change even if your query uses different vocabulary than the original commit message.
- 3Guide AI agents on tool selectionInstruct an AI agent to use semantic search for conceptual questions and pickaxe search when specific symbols are known.
Written from the project's README. Every use case is checked against a quote from it.
How to install Git Why MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Git Why MCP in Claude Code
$ claude mcp add git-why -- npx -y @alliecatowo/git-why mcpInstall Git Why MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"git-why": {
"command": "npx",
"args": [
"-y",
"@alliecatowo/git-why",
"mcp"
]
}
}
}Install Git Why MCP in VS Code
.vscode/mcp.json
{
"servers": {
"git-why": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@alliecatowo/git-why",
"mcp"
]
}
}
}Install Git Why MCP in VS Code CLI
$ code --add-mcp '{"name":"git-why","type":"stdio","command":"npx","args":["-y","@alliecatowo/git-why","mcp"]}'Install Git Why MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"git-why": {
"command": "npx",
"args": [
"-y",
"@alliecatowo/git-why",
"mcp"
]
}
}
}Install Git Why MCP in Codex
$ codex mcp add git-why -- npx -y @alliecatowo/git-why mcpInstall Git Why MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.git-why] command = "npx" args = ["-y", "@alliecatowo/git-why", "mcp"]
Install Git Why MCP in Gemini CLI
$ gemini mcp add -s user git-why npx -- -y @alliecatowo/git-why mcpInstall Git Why MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"git-why": {
"command": "npx",
"args": [
"-y",
"@alliecatowo/git-why",
"mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @alliecatowo/git-why 0.2.0 in an isolated container with no network and no keys. It answered and listed 2 tools.
Git Why MCP tools 2
Read from the server with tools/listgit_why_searchFind the commits that explain WHY code is the way it is: the rationale behind a design, whether an approach was already tried and reverted, what a past incident was, or who established an area. USE THIS when you cannot name the exact symbol or string to search for. On questions where keyword search fails, it scores ~18x `git log --grep`. DO NOT USE THIS when you already know the identifier. `git log -S<symbol>` is measurably better for that (Hit@10 0.950 vs 0.350) -- if you can see the name in the code, run pickaxe search instead. For the CURRENT state of the code rather than its history, use a code search tool; this only reads history. Ask the way you would ask a colleague who was there. Vague, natural phrasing works BETTER than technical phrasing here -- restating a question in technical vocabulary measurably trades away more recall than it gains in precision. Results are ranked by relevance, not proven. It misses roughly seven hard questions in ten. Verify a result with `git show <sha>` before acting on it, and if nothing looks relevant say so rather than constructing a rationale from a weak match.
git_why_statusReport whether this repository's history index exists and is current. USE THIS when git_why_search returns an index error, or before searching a repository for the first time. The answer is actionable: if "state" is not "current", run `git why index --if-needed` in a shell -- it is idempotent and takes about 0.2s when there is nothing to do. An index is built once per repository and shared by all its worktrees. A first build on a large repository takes minutes, so do it deliberately rather than inside a loop.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablealliecatowo/git-why is public and reachablegithub.com/alliecatowo/git-why ↗Pass
- Package names this repository as its source@alliecatowo/git-why names alliecatowo/git-why as sourcenpmjs.com/package/@alliecatowo/git-why ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @alliecatowo/git-whynpmjs.com/package/@alliecatowo/git-why/v/0.2.0#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-06github.com/alliecatowo/git-why ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @alliecatowo/git-whyPass
- No critical advisory in the package or its dependencies11 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubGit 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.
First run
cd your-repo
git why "why do we retry twice before giving up"
The first query downloads a small embedding model (about 32 MB, checksum-verified,
cached under ~/.cache/git-why/models) and indexes the repository's history into
.git/why/; later queries are incremental. Behind a proxy or offline, see
HTTPS_PROXY, GIT_WHY_MODEL_BASE_URL (mirror) and GIT_WHY_OFFLINE in
docs/operations.md. git why status shows whether the
index is current.
Use it with an agent
Two plugins ship in plugins/:
| plugin | what you get |
|---|---|
git-why |
The MCP server, a routing skill, and an index-management skill. |
git-why-full |
The same, plus zg for current-code search and a history-explorer agent for questions that need several searches. |
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.
Any other MCP client can run the server directly: npx -y @alliecatowo/git-why mcp
(or git why mcp once installed). It is also listed in the
MCP registry as
io.github.alliecatowo/git-why.
See docs/plugin.md.
Make it faster (optional)
git why server on
Holds the index, the embedding model and the lineage table open between queries. On curl — 30,000 commits — that is 569 ms a query down to 286 ms. Searches use it automatically once it is running.
It can never be the reason a search fails: if no daemon is running, or it is
unreachable, or your index moved under it, the query runs directly instead.
--daemon=direct opts out, --daemon=server requires one. See
docs/daemon.md.
Why
git log --grep only matches words you already know. The reason code
changed usually lives in a commit message, but you rarely remember its exact
wording — you remember the problem, in your own words, months later.
Look again at the first example above: the query is "reconnecting subscribed twice" and the commit is titled "Stop duplicate subscriptions after reconnect." They share almost no vocabulary. That's not a coincidence Git Why is showing off — it's the actual point of a semantic index. It carries the meaning of the change, not just its words, alongside an ordinary keyword index for when you do know the exact term.
Git Why retrieves historical evidence: the commit, the author's actual words, and the relevant diff. Historical commit messages are assertions by their authors, not infallible accounts of intent, and some reasons were never committed at all — Git Why will not manufacture those.
Measured, not claimed
Every number below is written into this file by bench/report.mjs from raw
run data, and CI fails if it drifts — no figure here was typed by hand. Full
methodology, limits, and the negative results are in
docs/report.md.
Against the tools you would otherwise use
174 recall questions — you remember a problem but cannot name anything in the
commit that fixed it — derived mechanically from 6 pinned real repositories
(curl, redis, requests, ripgrep, caddy, zod). Every question is verified unanswerable by
keyword search before it enters the set: if git log --grep or git log -S finds the
answer from the question's own words, the case is discarded.
| strategy | Hit@1 | Hit@5 | MRR | returned nothing |
|---|---|---|---|---|
| git why | 0.201 | 0.374 | 0.266 | 0 |
| zg (semantic code search) | 0.017 | 0.040 | 0.026 | 2 |
| git log -G | 0.006 | 0.017 | 0.011 | 15 |
| git log --grep | 0.000 | 0.011 | 0.003 | 0 |
| git log --grep --all-match | 0.000 | 0.000 | 0.000 | 109 |
| git log -S | 0.000 | 0.000 | 0.000 | 15 |
10.2x zg and 23x the best Git-native strategy — and the only approach that answers nearly every question rather than returning an empty set.
Where it loses
When you can name the symbol, use pickaxe search instead. On cross-file causal
questions, git log -S scores Hit@10 0.950 against git why's 0.350.
Semantic search has no advantage over a tool you can hand the exact literal.
That boundary is the honest positioning, and the shipped skill tells agents both halves:
- cannot name the term →
git why - can name the term →
git log -S - current code, not history →
zg
Scale and cost
Does it help an agent?
Retrieval quality is not the product. The question is whether an agent answering a real question does it more accurately, or in fewer turns, with the tool than without. Four arms over the same frozen tasks, paired per task, with token counts reconciled against the provider's own accounting database.
| model | paired n | accuracy W-L | median tool calls saved |
|---|---|---|---|
| gemini-3.1-flash-lite | 6 | 1-2 | 2.5 |
| claude-haiku-4-5 | 9 | 1-1 | 1 |
| claude-sonnet-5 | 8 | 0-0 | 1 |
| deepseek-v4-flash | 8 | 0-0 | 3.5 |
| gemini-2.5-flash-lite | 6 | 2-1 | 1 |
| gemini-3.1-flash-lite | 7 | 2-0 | 1 |
| gemini-3.5-flash | 6 | 0-0 | 0.5 more |
Results are mixed across models. At single-digit paired n per model this is descriptive, not significant, and it is reported that way deliberately — the direction is consistent, the magnitude is not established. Full method and per-arm figures in the benchmark report.
Method, per-arm figures and the registered hypothesis: docs/report.md.
| measurement | result |
|---|---|
| Index across 6 real repos (56,781 commits) | 5.51–7.84 KB/record |
| curl-curl (30,000 commits, 182,772 records) | 1.37 GiB, 7.84 KB/record |
Query on curl-curl (30,000 commits) with git why server on |
384 ms p50, 491 ms p95 |
| The same query with no daemon | 851 ms p50, 1371 ms p95 |
| Diff/evidence ingestion, real-repo ablation | earns its cost, ΔHit@5 +0.375 |
What works, and what does not
Eight optimisations were implemented and measured. One survived.
The one that did: lexical overlap between the question and the commit's own message, reranked over a candidate pool deeper than the result list. Weight chosen on a dev half, evaluated once on the held-out half — +26% MRR and +44% Hit@1 on cases it never saw. Shipped.
The seven that did not: a prose-tuned embedding model, pseudo-relevance feedback, a prose-commit penalty, caller-side query restatement, wider result windows, structural expansion, and phrase fusion. None improved MRR.
What made the difference was not a better idea but a different question. The
seven all asked "does this rank better". The one that worked started by asking
where the right commit actually is — and found that a quarter of the corpus is
retrieved but ranked below 5, which is a reordering problem, while 42% is never
retrieved at all, which is not. See
docs/decisions.md.
The remaining headroom is that 42%: a recall problem in the embedding itself.
That is now measured rather than guessed —
docs/embedding.md compares ten models on a fixed pool.
Transformer embedders score +41% (jina-v2-small) and +64%
(jina-v2-base) MRR over the shipped static one, at 191x and 1287x the
indexing time plus an ONNX runtime. Both are available opt-in; the default
stays fast and dependency-free, because a tool that installs in seconds and
indexes in under a minute should not quietly become one that needs fifteen
hours.
It is also wrong most of the time. Hit@5 of 0.374 means the right commit is
outside the top five on 62.6% of these questions. It beats every alternative on
them and still fails on most. Treat a result as a lead to verify with git show, never as
established fact.
When to use ordinary Git instead
Git Why is ranked retrieval over a semantic index. That's the wrong tool for some jobs, and Git already has the right one:
- A known exact string.
git log -Sandgit log -Gare exhaustive. Keyword mode here is ranked, not exhaustive. - An exhaustive search.
ripgrepover a checkout, orgit grep. - Verifying causality. Similarity is not a timeline. Confirm ancestry
with
git merge-base,git log --ancestry-pathandgit show.
Git Why is for the case where you remember what happened but not what it was called.
Learn more
- Documentation site — guided install, how retrieval works, CLI reference, FAQ.
ROADMAP.md— pull requests,gh why, wikis, and what would need measuring before any of it ships.docs/embedding.md— nine embedding models measured, the +41% one you can opt into, and why the default did not change.docs/daemon.md— the optional daemon: what it holds warm, why it can never break a search, and its security posture.docs/indexes.md— where indexes live, worktrees, submodules, monorepos, disk use, and the shared model cache.docs/examples.md— real output on real repositories, including a case where this is the wrong tool.docs/plugin.md— both plugins, the MCP tools, the skills, and why there is no hook.docs/decisions.md— what was tried and rejected, with the measurements. Seven optimisations that did not work.docs/install.md— every install path and uninstall, including where the index and model cache live on disk.docs/operations.md— the full operational contract: durability, concurrency, exit codes, history scope, coverage limits.docs/report.md— the benchmark report this README's numbers come from.docs/spec.md— the build specification this was written against. Source comments cite its sections, so it is kept as provenance rather than as user documentation.
Development
mise setup # install dependencies, then doctor
mise check # format, lint, typecheck, protocol hash, unit tests
mise test:integration # real repositories, real storage, real locks
mise test:package # pack, install into a clean prefix, invoke through Git
mise site:build # build the docs/marketing site in site/
mise tasks # everything else, including every benchmark
Numbers in README.md, site/index.md and docs/report.md are written by
bench/report.mjs from raw run data — CI fails if you edit one by hand. The
man page, the site's CLI reference and all three shell completions are checked
against git why -h, which is the only place the flag set is defined.
See docs/contributing.md for module ownership and how
to cut a release.
License
Git Why MCP questions
How do I add Git Why MCP to Claude Code?
Run claude mcp add git-why -- npx -y @alliecatowo/git-why mcp in your terminal. Add --scope user to make it available in every project.
How do I add Git Why MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Git Why MCP provide?
It exposes 2 tools, including git_why_search, git_why_status.
How is Git Why different from git blame?
While git blame tells you who changed the code, git why finds the history that explains why the change was made.
Does the tool generate its own explanations for code changes?
No, it retrieves actual historical evidence including the commit, the author's words, and the relevant diff without manufacturing explanations.