Summary
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.
Plug Mailtrap into your AI workflow and let it handle the email.
Connect Mailtrap MCP →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →
Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.
Try For Free →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Tools
Public tool metadata for what this MCP can expose to an agent.
8 tools
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
idstringContext 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
domainstringFilter to a specific domain.
topicstringFilter 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
branchstringBranch name to find PR for (e.g. 'docs-fix'). Useful when running from a different branch or worktree.
idsstringJSON array string of context IDs. If omitted, posts for all published contexts on current PR.
pr_numbernumberPR 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
idsstringJSON 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
commitsarrayOptional 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.
domainstringOptional domain category (e.g. 'authentication', 'api-design'). Auto-categorized if omitted.
markdownstringContext document in XML format (preferred) or structured markdown (legacy).
repo_rootstringAbsolute 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...
topicstringOptional 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
domainstringFilter results to a specific domain (e.g., 'architecture', 'debugging', 'performance').
limitnumberMaximum number of results to return (default 10, max 20).
querystringSearch query — natural language or specific terms (file paths, function names, commit SHAs). Examples: 'why did we change auth', 'billing.go', 'abc1234'.
repostringFilter 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_rootstringAbsolute 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
forcebooleanSkip all dedup checks and re-sync even if already synced. Use to recover from stale push-state.
idsstringJSON array string of context IDs to sync. If omitted, syncs all local contexts.
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
Links
Featured
Plug Mailtrap into your AI workflow and let it handle the email.
Connect Mailtrap MCP →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.
Try For Free →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Configuration
GITWHY_API_KEYsecretGitWhy API key for cloud sync, publish, and PR comment features. Not required for local-only context saving.
Categories
Registryactive
Packagegitwhy-mcp
TransportSTDIO
AuthRequired
UpdatedApr 1, 2026
