Codebase intelligence
for LLM agents.

Why it matters

Every tool response carries a real BPE token count. Real numbers on this codebase (~950 files, ~8,000 symbols, ~5,600 edges, v0.94):

Three leverage layers that stack

Skip a layer and you leave value on the table. Most integrators wire up the atomic tools, miss the hook (the highest-leverage layer per token saved), and never branch on _meta — extracting ~20% of the available leverage. Full frame: loop-leverage-layers.md.

Same investigation, three shapes

Real task: "why does the TestExtractGoCalls_Closure test sometimes emit phantom CALLS edges?" Three integration shapes, three radically different token / latency profiles.

How it's stored under the hood

Three co-located indexes in one shared symbol table — populated by a single AST pass. No duplication, no sync overhead. (Distinct from the three leverage layers above — those are how an agent consumes pincher; these are how pincher stores the data.)

30 tools, one mental model

Every tool returns a _meta envelope with tokens used / saved and latency. Pick the tool by what you're trying to do, not by the underlying index.

Install

Pick your platform. Every install produces the same single binary; service templates live under packaging/.

git clone https://github.com/kwad77/pincher
cd pincher
go build -o pincher ./cmd/pinch/

# Drop the pincher policy block into your project's CLAUDE.md
./pincher init                # ./CLAUDE.md
./pincher init --global       # ~/.claude/CLAUDE.md

# Run the HTTP dashboard alongside your MCP client
./pincher --http 127.0.0.1:8080

# Or open the dashboard on demand — auto-starts the server if needed
./pincher web

# Stay current — pulls + rebuilds in place from this checkout
./pincher update

# Once a tap is published (see packaging/homebrew/pincher.rb)
brew tap kwad77/pincher
brew install pincher
brew services start pincher

PINCHER_HTTP_KEY=$(openssl rand -hex 16)
docker run -d --name pincher \
  -v pincher-data:/data \
  -p 8080:8080 \
  -e PINCHER_HTTP_ADDR=:8080 \
  -e PINCHER_HTTP_KEY \
  ghcr.io/kwad77/pinchermcp:latest

# Download the matching archive from the releases page, then:
tar -xzf pincher-v1.9.0-linux-amd64.tar.gz
sudo mv pincher-v1.9.0-linux-amd64 /usr/local/bin/pincher
pincher --version

One command per host

pincher init --target=<host> writes the host's project-rules / hook file at the canonical path. --target=detect walks the local filesystem and wires up every detected host in one pass.

# Wire up whichever editor / agent is installed locally
pincher init --target=detect

# Or pick a specific host
pincher init --target=claude         # ./CLAUDE.md (Claude Code CLI)
pincher init --target=cursor         # ./.cursor/rules/pincher.mdc
pincher init --target=zed            # ./.zed/settings.json
pincher init --target=codex          # ~/.codex/config.toml
pincher init --target=vscode-copilot # ./.github/copilot-instructions.md
pincher init --target=jetbrains      # ./.junie/guidelines.md  (v0.71)
pincher init --target=antigravity    # ./.agents/rules/pincher.md  (v0.72)
pincher init --target=antigravity-mcp # ~/.gemini/antigravity/mcp_config.json  (v0.89)
pincher init --target=goose          # ./.agents/plugins/pincher Open Plugins hook
pincher init --target=windsurf       # ./.windsurf/rules/pincher.md
pincher init --target=gemini         # ~/.gemini/settings.json

Goose users also add Pincher as a stdio MCP extension in ~/.config/goose/config.yaml; see the Goose tutorial for the two-piece MCP + hook setup.

Manual MCP wiring (if you'd rather)

Any MCP-compatible client works. Two example configs — the command is the same everywhere.

{
  "mcpServers": {
    "pincher": {
      "type": "stdio",
      "command": "/path/to/pincher"
    }
  }
}

{
  "mcpServers": {
    "pincher": {
      "command": "/path/to/pincher"
    }
  }
}

Where pincher is going

Pre-1.0. The cadence: nine minor releases per phase ending at a stable promotion (v0.60, v0.70, v0.80, v0.90, v1.0). Phase 3 closed at v0.80 stable, Phase 4 (composite-tool buildout) at v0.90 stable; currently in Phase 5 — the v1.0 supply-chain + measurement + RC dogfood path.