GitWhy — The Context Layer for Git

gitwhy-cli/gitwhy

Connects Claude to GitWhy's context engine so you can save and retrieve the reasoning behind code changes directly in git commits. Exposes tools to store structured AI session context, search past decisions, browse context trees, and post summaries to pull requests. Useful when you're iterating with an AI coding agent and want to preserve why you made certain architectural choices or rejected alternatives, not just what changed. Requires the GitWhy CLI installed locally and works through MCP tools or natural language triggers like "save this session" or "what context do we have on authentication." Think of it as git blame for AI-assisted development decisions.

tools: 8
auth: Secret needed
transport: STDIO
env var: 1
last updated: Apr 1, 2026

View on GitHub

Tools

8 tools

Public tool metadata for what this MCP can expose to an agent.

gitwhy_getRetrieve a saved context by its ID. Returns the full markdown content including metadata, reasoning, and file changes. Use when you know the exact context ID (e.g., from gitwhy_search or gitwhy_list results) and need the complete details. CLI alternative: `git why get <id>`.1 params

Retrieve a saved context by its ID. Returns the full markdown content including metadata, reasoning, and file changes. Use when you know the exact context ID (e.g., from gitwhy_search or gitwhy_list results) and need the complete details. CLI alternative: `git why get <id>`.

Parameters* required

idstring

Context ID (e.g. 'ctx_a1b2c3d4') to retrieve.

gitwhy_listBrowse saved contexts and the domain/topic tree structure. Use to discover what contexts exist in this repo. Call with no args to see the domain/topic hierarchy. Add filters to drill down into a specific domain or topic. CLI alternative: `git why tree` (tree view) or `git why...2 params

Browse saved contexts and the domain/topic tree structure. Use to discover what contexts exist in this repo. Call with no args to see the domain/topic hierarchy. Add filters to drill down into a specific domain or topic. CLI alternative: `git why tree` (tree view) or `git why...

Parameters* required

domainstring

Filter to a specific domain.

topicstring

Filter to a specific topic within a domain. Requires domain.

gitwhy_post_prPost or update a GitHub PR comment summarizing the development context for linked commits. Use when the developer wants reviewers to see the 'why' behind their changes directly on the PR. Contexts must be published first via gitwhy_publish. CLI alternative: `git why post-pr [c...3 params

Post or update a GitHub PR comment summarizing the development context for linked commits. Use when the developer wants reviewers to see the 'why' behind their changes directly on the PR. Contexts must be published first via gitwhy_publish. CLI alternative: `git why post-pr [c...

Parameters* required

branchstring

Branch name to find PR for (e.g. 'docs-fix'). Useful when running from a different branch or worktree.

idsstring

JSON array string of context IDs. If omitted, posts for all published contexts on current PR.

pr_numbernumber

PR number. If omitted, auto-detects from current branch using gh CLI.

gitwhy_publishMake synced contexts visible to the team (shared). Auto-syncs to cloud if not already synced. Use when the developer wants teammates to see their context — typically after a PR is merged or a milestone is reached. CLI alternative: `git why push <context-id> --share`.1 params

Make synced contexts visible to the team (shared). Auto-syncs to cloud if not already synced. Use when the developer wants teammates to see their context — typically after a PR is merged or a milestone is reached. CLI alternative: `git why push <context-id> --share`.

Parameters* required

idsstring

JSON array string of context IDs to publish.

gitwhy_saveSave development context (reasoning, decisions, trade-offs) for the current coding session. Use after completing a meaningful unit of work. PREFERRED FORMAT: Wrap content in <context> XML tags: <context> <title>Short title of what was done</title> <agent>your-agent-name (model...5 params

Save development context (reasoning, decisions, trade-offs) for the current coding session. Use after completing a meaningful unit of work. PREFERRED FORMAT: Wrap content in <context> XML tags: <context> <title>Short title of what was done</title> <agent>your-agent-name (model...

Parameters* required

commitsarray

Optional list of commit SHAs made during this session. When provided, only these commits are included in the saved context. When omitted, commits are auto-detected from git history.

domainstring

Optional domain category (e.g. 'authentication', 'api-design'). Auto-categorized if omitted.

markdownstring

Context document in XML format (preferred) or structured markdown (legacy).

repo_rootstring

Absolute path to the project's git repository root. Pass this when the MCP server may have started from a different directory (e.g., home directory). When provided, updates the repo root for this a...

topicstring

Optional topic within the domain (e.g. 'jwt-middleware'). Auto-categorized if omitted.

gitwhy_searchSearch saved contexts by keyword or natural language query. Returns matching context summaries ranked by relevance using hybrid keyword + semantic search. Searches across titles, reasoning, code snippets, file paths, and commit SHAs. Results include local contexts and (if auth...4 params

Search saved contexts by keyword or natural language query. Returns matching context summaries ranked by relevance using hybrid keyword + semantic search. Searches across titles, reasoning, code snippets, file paths, and commit SHAs. Results include local contexts and (if auth...

Parameters* required

domainstring

Filter results to a specific domain (e.g., 'architecture', 'debugging', 'performance').

limitnumber

Maximum number of results to return (default 10, max 20).

querystring

Search query — natural language or specific terms (file paths, function names, commit SHAs). Examples: 'why did we change auth', 'billing.go', 'abc1234'.

repostring

Filter results to a specific repository (owner/name format). Default: current repo.

gitwhy_statusCheck GitWhy setup state, pending commits, and sync status for the current repo. Use to determine whether to suggest saving context (e.g., 'there are 5 unsaved commits'), check if the user is authenticated for cloud features, or verify GitWhy is properly initialized. IMPORTANT...1 params

Check GitWhy setup state, pending commits, and sync status for the current repo. Use to determine whether to suggest saving context (e.g., 'there are 5 unsaved commits'), check if the user is authenticated for cloud features, or verify GitWhy is properly initialized. IMPORTANT...

Parameters* required

repo_rootstring

Absolute path to the project's git repository root. Pass this to correct the detected repo root if it resolved to the wrong directory (e.g., home directory). Updates the repo root for this and all...

gitwhy_syncUpload local contexts to the GitWhy cloud as private (not shared with team). Use after saving contexts locally to back them up to the cloud. Synced contexts remain private until explicitly published with gitwhy_publish. CLI alternative: `git why push <context-id>` (syncs speci...2 params

Upload local contexts to the GitWhy cloud as private (not shared with team). Use after saving contexts locally to back them up to the cloud. Synced contexts remain private until explicitly published with gitwhy_publish. CLI alternative: `git why push <context-id>` (syncs speci...

Parameters* required

forceboolean

Skip all dedup checks and re-sync even if already synced. Use to recover from stale push-state.

idsstring

JSON array string of context IDs to sync. If omitted, syncs all local contexts.

Configuration

GITWHY_API_KEYsecret

GitWhy API key for cloud sync, publish, and PR comment features. Not required for local-only context saving.

Readme

GitWhy Agent Skills

Agent skills for GitWhy — save the reasoning, decisions, and trade-offs behind AI-generated code.

Install

npx skills add gitwhy-cli/gitwhy

Or install for a specific agent:

npx skills add gitwhy-cli/gitwhy --agent claude
npx skills add gitwhy-cli/gitwhy --agent cursor
npx skills add gitwhy-cli/gitwhy --agent codex

What's Included

`gitwhy` skill

Teaches your AI coding agent to save, retrieve, and search structured context linked to git commits. Works via MCP tools or CLI commands.

Trigger phrases:

"Save this session with GitWhy"
"What context do we have on authentication?"
"Show me the context tree"
"Post the context to the PR"

Prerequisites

Install the GitWhy CLI first:

curl -fsSL https://gitwhy.dev/install.sh | sh

Or via Homebrew:

brew install gitwhy-cli/tap/git-why

Then run setup:

git why setup

Details

Repository: github.com/gitwhy-cli/gitwhy
Categories: Developer Tools, Search & Web Crawling
Package: gitwhy-mcp
Transport: STDIO
Auth: Required
Registry: MCP registry, active

Related Developer Tools MCP servers

View all

Intelligence Mcpgoodmeta/intelligence-mcpAgent payments ecosystem intelligence. Scans GitHub/HN/npm across AP2, ACP, x402, MPP, UCP.0stars

Capabilitymap Nexus Mcphadinkof/capabilitymap-nexus-mcpGitHub Capability Router (666 repos, 96.4% token savings) & 5-Vector Prompt-Injection Firewall.0stars

Herohunt Mcpherohunt-ai/herohunt-mcpPeople search API - find 1 billion candidates across LinkedIn and GitHub with real-time data.0stars

Can Seehurleysk/can-seeLet AI agents see and interact with terminal/CLI apps via PNG screenshots0stars

Ink MCPmldotink/mcpDeploy and manage applications, databases, domains, and git repos0stars

Markdown Renderer APIbr0ski777/markdown-renderer-x402Render markdown to styled HTML with light/dark/github themes. x402 micropayment.0stars

GitWhy — The Context Layer for Git

Tools

Configuration

Readme

GitWhy Agent Skills

Install

What's Included

gitwhy skill

Prerequisites

Links

Details

Related Developer Tools MCP servers

`gitwhy` skill