# Git Why

> Git Why is an open-source MCP server for developer tools. Search Git history by meaning to find the commit that explains why code is the way it is. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Linux
- **Website:** https://alliecatowo.github.io/git-why/
- **Repository:** https://github.com/alliecatowo/git-why
- **MCP Registry name:** io.github.alliecatowo/git-why
- **Categories:** developer tools
- **Listing updated:** 2026-11-16

## About

Git Why returns evidence rather than generated answers: a real commit, its author's own message and the relevant diff. Full-text and vector search run separately over every reachable commit and are fused with Reciprocal Rank Fusion, so an exact identifier and a half-remembered paraphrase both work. Embedding uses a small model in-process, so repository text stays local, and after one checksummed download of about 32 MB it works offline.

Beyond search it can resolve the first, last or removed commit for a subject, lay out a timeline, and rank who established an area by commit relevance. An optional daemon keeps the index warm for roughly twice the speed and is never required.

The project publishes unusually candid benchmarks: on 174 recall questions it scores Hit@1 of 0.201, well above other approaches, but it says git log -S is the better choice when you can name the symbol. That advice is built into the skill shipped with its agent plugins.

## Features

- **Semantic history search:** Finds commits by meaning when you remember no keywords.
- **Original commit evidence:** Returns the real commit message and diff, not a generated summary.
- **Timeline and owners:** Shows how a subject changed and who established an area.
- **Local and offline:** Embeds in-process and runs offline after one model download.
- **Optional daemon:** Keeps the index warm for faster queries without being required.
- **Agent plugins:** Ships MCP, a routing skill and an index-management skill.

## Good for

- Find why a retry or workaround was added
- Locate the commit behind a half-remembered bug
- See how a subsystem changed over time
- Let an agent check history before changing legacy code

## Install

### Claude Code (Terminal)

```sh
claude mcp add git-why -- npx -y @alliecatowo/git-why
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "git-why": {
      "command": "npx",
      "args": [
        "-y",
        "@alliecatowo/git-why"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "git-why": {
      "command": "npx",
      "args": [
        "-y",
        "@alliecatowo/git-why"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "git-why": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@alliecatowo/git-why"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "git-why": {
      "command": "npx",
      "args": [
        "-y",
        "@alliecatowo/git-why"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "git-why": {
      "command": "npx",
      "args": [
        "-y",
        "@alliecatowo/git-why"
      ]
    }
  }
}
```

## Tools

- `git_why_search`: Search commit history by meaning and text
- `git_why_status`: Report whether the repository index is current

## FAQ

### How do I install it?

With npm install -g @alliecatowo/git-why, Homebrew, or from source; it needs Node 22.12 or newer.

### Does it send my code anywhere?

No. Embedding runs in-process, so repository text never leaves your machine.

### Does it generate explanations?

No. It retrieves evidence; the reason is found or it is not there.

### When should I use something else?

When you can name the symbol, git log -S is better, according to the project's own benchmarks.

### Is Git Why free?

Yes. Git Why is open source, so you can use and self-host it for free.

### How do I add Git Why to Claude Code?

Run this command in your terminal: claude mcp add git-why -- npx -y @alliecatowo/git-why

### What are the best alternatives to Git Why?

The closest alternatives to Git Why are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/git-why
