gitwhy

The shared AI context engine for git — save, search, and share the reasoning behind code changes.

CommunityOnlineAPI key requiredGlobalFreeRead-only

What it can do

  • Gitwhy Get: 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 g
  • Gitwhy List: 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
  • Gitwhy Post Pr: 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

What data it sees

Do you need an account

An API key from the service settings is required

The shared AI context engine for git — save, search, and share the reasoning behind code changes. Captures the why behind every commit and slide on PRs for coding agents.

How to connect

How to connect gitwhy to Claude

The server address to paste into Claude settings:

https://gitwhy--gitwhy-cli.run.tools

  1. Open Claude (claude.ai or the desktop app).
  2. Go to Settings → Connectors.
  3. Click Add custom connector.
  4. Paste the server address copied below into Remote MCP server URL and click Add.
  5. In a chat, click + → Connectors and switch the new connector on.

Custom connectors are available on Free, Pro, Max, Team and Enterprise plans (Free is limited to one). On Team and Enterprise an organization Owner adds the connector first under Organization settings → Connectors.

Authorization

After you click Add, a sign-in window for the service opens. Sign in with your own account and approve access. Claude never sees your password.

How to connect gitwhy to ChatGPT

The server address to paste into ChatGPT settings:

https://gitwhy--gitwhy-cli.run.tools

  1. Open ChatGPT in a browser (chatgpt.com). A Plus, Pro, Business, Enterprise or Edu plan is required.
  2. Turn on developer mode once: Settings → Apps → Advanced settings → Developer mode.
  3. Open Settings → Connectors and click Create.
  4. Fill in the form: Name (anything), Description (one line about what the service does), MCP server URL (copy it below).
  5. Under Authentication choose OAuth if the service requires sign-in, otherwise None. Click Create.
  6. In a new chat open + → Apps/Connectors and enable the connector.

OpenAI has renamed this section before (Connectors → Apps/Plugins). If the label differs, search settings for "developer mode". On Business/Enterprise workspaces an admin must allow custom connectors first.

Authorization

On first use ChatGPT opens the service's sign-in window. Sign in and approve access.

How to connect gitwhy to Cursor

The server address to paste into Cursor settings:

https://gitwhy--gitwhy-cli.run.tools

Fastest: click Open in Cursor below and confirm the prompt.

Manually:

  1. In Cursor open Settings → Cursor Settings → MCP and click Add new global MCP server.
  2. Paste the JSON copied below into ~/.cursor/mcp.json (per project: .cursor/mcp.json in the repo root).
  3. Save the file. The server appears in the MCP list; authorize it there if asked.

Authorization

If the service needs sign-in, an authorize button appears next to the server in the MCP list.

Server tool list (8)

Raw names from tools/list. Only developers need these.

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>`.
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 log` (list view).
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 [context-id...]`.
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`.
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)</agent> <tags>keyword1, keyword2, keyword3</tags> <story> Organize by phases. Write in first-person engineering journal style. Phase 1 — Title: What user asked, what you did, challenges faced, how you resolved them. Include back-and-forth with the user where it shaped the outcome. </story> <reasoning> Why you chose this approach. <decisions> - Decision — rationale </decisions> <rejected> - Alternative — why rejected </rejected> <tradeoffs> - Trade-off accepted — justification </tradeoffs> </reasoning> <files> path/to/file — new — Description path/to/other — modified — Description </files> <tools>MCPs and resources used</tools> <verification>Test/build results</verification> <risks>Open questions or risks</risks> </context> Required tags: title, story, reasoning. All others (including files) are optional. Context ID, repository, branch, date, and commits are auto-populated. CLI alternative: write content to a file, then run `git why save --file context.md`. Or pipe directly: `echo '<context>...</context>' | git why save`.
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 authenticated) cloud workspace contexts including team-shared contexts. Use for finding past decisions, understanding why code was written, or discovering relevant prior work. Use gitwhy_get <context_id> to read the full context. CLI alternative: `git why search "<query>"`.
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: Check the repo_root field in the response. If it shows your home directory, pass repo_root with your project's absolute path to correct it. CLI alternative: `git why log` (list saved contexts) and `git why tree` (show structure).
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 specified contexts as private).