Home / Tutorial / Getting started

Getting started

Five steps: install the binary, wire pincher into your editor, index a project, and confirm the agent can see it. About five minutes.

What pincher is — in one paragraph

pincher is a single Go binary that runs locally as an MCP server. It indexes a codebase into three co-located layers — a byte-offset symbol store, a knowledge graph of CALLS/IMPORTS/READS edges, and FTS5 full-text search — and exposes them to your AI agent as callable tools. The agent answers "who calls this?" or "read this function in context" with a cheap indexed lookup instead of reading whole files. No cloud, no CGO, no daemon you manage by hand.

Step 1 — Install the binary

1

Grab the release for your platform from the Install section on the home page — a tarball (macOS / Linux) or zip (Windows), or Homebrew / Scoop / Docker. Every path produces the same single pincher binary. Put it on your PATH and check it: 

pincher --version

Step 2 — Run the setup wizard

2

pincher setup is an interactive wizard. It detects which editors and agents you have installed, pre-checks them, and writes the config each one needs — so you never have to look up a flag name. 

pincher setup

Use ↑/↓ to move, space to toggle a host, enter to continue. The wizard walks you through host selection, a short options step (global rules, the Claude PreToolUse hook, git hooks), a review of exactly what files it will write, and then applies it.

Scripted installs Prefer flags? pincher init --target=cursor (and --target=claude, codex, …) does the same write non-interactively. setup is the guided front end; init is the scriptable one. Run pincher init -h for every target.

Step 3 — Index your first project

3

Change into a repository and index it. pincher walks the tree (respecting .gitignore), extracts symbols, and builds the graph: 

cd ~/code/my-project
pincher index

It prints a one-line summary — symbols, edges, files, duration — and, on a project's first index, a pointer to what comes next. Re-running pincher index later is incremental: only changed files are re-extracted.

You usually don't need to Once an editor is wired up, pincher's background watcher keeps the index fresh automatically. The manual pincher index is handy for the very first build and for CI.

Step 4 — Confirm it works

4

Two quick checks:

pincher doctor      # schema, index freshness, any advisories
pincher web         # opens the dashboard in your browser

doctor should report your project with a recent indexed_at and no advisories. web opens a local dashboard showing the same project's symbol and edge counts.

Step 5 — Ask your agent

5

Open the editor you wired up in Step 2 and ask the agent a code-navigation question — "what calls processOrder?", "show me the auth middleware". If pincher is connected, the agent answers from the index instead of grepping. You can confirm the MCP connection in your host's MCP panel (it should list pincher with its tools).

Heads up — `pincher` by itself Running bare pincher in a terminal prints an orientation and exits: pincher is an MCP server, launched by your editor over a pipe, not run directly. The commands you run by hand are the subcommands — setup, index, web, doctor.