Pinchy, the pincherMCP mascot — a pixel-art crab holding a copper penny
Single binary · pure Go · no cloud

Codebase intelligence
for LLM agents.

pincherMCP indexes any repo into a byte-offset symbol store, a knowledge graph, and a BM25 full-text search — all populated in one AST pass — then exposes 16 tools over MCP stdio or HTTP REST. Agents get what they need in tokens, not files.

Install View on GitHub →

Why it matters

Every tool response carries a real BPE token count. Real numbers on this codebase (13 files, 618 symbols, 5,785 edges):

~95%
Token reduction
vs reading whole files
<1ms
Symbol fetch
(byte-offset seek)
<5ms
BFS depth 3
call-graph trace
19 langs
6 AST-backed + 13 regex
extractors

How it works

Three co-located indexes, one shared symbol table. No duplication, no sync overhead.

Byte-offset store Layer 1

Every symbol persists start_byte/end_byte. Retrieval is 1 SQL lookup + 1 os.Seek + 1 os.Read. No re-parsing, no line scanning, sub-millisecond on any symbol.

Knowledge graph Layer 2

Symbols are graph nodes; CALLS and IMPORTS are edges. Cypher-subset queries compile down to three SQL strategies (scan, JOIN, BFS) for sub-ms structural lookups.

FTS5 full-text Layer 3

Virtual table with BM25 ranking over names, signatures, and docstrings. Auto-synced via INSERT/UPDATE/DELETE triggers — you never manage it manually.

16 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.

Discovery

search, architecture, list, schema, health — orient on any project without reading files.

Retrieval

symbol, symbols, context — pull one symbol, a batch, or a symbol plus its direct dependencies. Byte-offset, O(1).

Graph

query (Cypher), trace (BFS call paths with risk labels), changes (git-diff → blast radius).

Knowledge

adr persists architectural decisions across sessions; fetch stores URL content as a searchable Document symbol.

Install

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

git clone https://github.com/kwad77/pincherMCP
cd pincherMCP
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 :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
docker run -d --name pincher \
  -v pincher-data:/data \
  -p 8080:8080 \
  -e PINCHER_HTTP_ADDR=:8080 \
  -e PINCHER_HTTP_KEY=$(openssl rand -hex 16) \
  ghcr.io/kwad77/pinchermcp:latest
# Download the matching archive from the releases page, then:
tar -xzf pincher-v0.3.0-linux-amd64.tar.gz
sudo mv pincher-v0.3.0-linux-amd64 /usr/local/bin/pincher
pincher --version

Point your MCP client at it

Any MCP-compatible client works. Three examples — the command is the same everywhere.

Claude Code

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

Cursor / Zed

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

How it compares

Byte-offset retrieval, a knowledge graph, and FTS5 full-text search, co-located in a single pure-Go binary — populated by one AST pass, no external services.

Capability pincherMCP CGO bindings Python services
Single binary✓needs C toolchainneeds Python + deps
MCP stdio✓variesvaries
HTTP REST + OpenAPI✓rarecommon
BPE token accountingreal cl100k—estimates
Blast-radius diff analysis✓——
Runtime dependenciesnone (pure Go)libc, libsqliteinterpreter