# hunch

hunch stores project decisions, bug history, rules, and open work in Git so AI agents can share the same record across sessions.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 11
- Author: davesheffer
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/davesheffer/hunch
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/davesheffer-hunch

## What it does

hunch gives agents a shared project record. It stores the reasons behind code, rejected approaches, past fixes, current findings, and unfinished commitments in Git, then exposes relevant entries through MCP. The server can also relate memory to code symbols and dependencies, check recorded constraints, and separate reported work from observed command results.

Run `hunch init` in a repository to index the code, configure supported integrations, and add memory instructions without replacing existing settings. The setup requires Node 22.13+ and a Git repository. Without either requirement, hunch will not start. Memory is advisory by default; blocking changes needs a trusted rule and strict enforcement.

Daily commands include `hunch context`, `hunch why`, `hunch impact`, `hunch check`, `hunch conform`, `hunch now`, and `hunch doctor`. The server can be connected to Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, or Gemini CLI.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add hunch -- npx -y @davesheffer/hunch
```

### Codex

**Platform CLI**
```bash
codex mcp add davesheffer-hunch -- npx -y @davesheffer/hunch
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "davesheffer-hunch": {
            "command": "npx",
            "args": [
                "-y",
                "@davesheffer/hunch"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "davesheffer-hunch": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@davesheffer/hunch"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add davesheffer-hunch npx -y @davesheffer/hunch
```

## When to use it
- record architectural decisions in Git
- trace the reason behind an old bug
- prepare focused task context for an agent
- check working changes against stored rules
- review commitments left by earlier sessions

## Example prompts
- Use hunch to explain why `src/auth.ts` is structured this way before I edit it.
- Create a focused brief for fixing logout with `hunch context`.
- Run `hunch check --working` and report conflicts with the recorded rules.

## Similar
- [ce-work](https://affpapa.org/en/nevibecode/skills/ce-work.md) — skill · 3600 installs
- [pi-delegate](https://affpapa.org/en/nevibecode/skills/pi-delegate.md) — skill · 3600 installs
- [om-auto-fix-issue](https://affpapa.org/en/nevibecode/skills/om-auto-fix-issue.md) — skill · 3600 installs
- [ce-resolve-pr-feedback](https://affpapa.org/en/nevibecode/skills/ce-resolve-pr-feedback.md) — skill · 3200 installs
- [copilot-delegate](https://affpapa.org/en/nevibecode/skills/copilot-delegate.md) — skill · 3100 installs
- [visual-pr](https://affpapa.org/en/nevibecode/skills/visual-pr.md) — skill · 3000 installs

## Other versions with the same name
- [hunch · prithviseran](https://affpapa.org/en/nevibecode/mcp/hunch.md) — ★ 22

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md