graphsnip

Give your coding agent the exact code it needs, not whole files, and prove the savings.

A token-saving layer on top of Graphify for Claude Code, GitHub Copilot and Codex.

_{The dashboard graphsnip report writes. Real data from the Flask codebase.}

At a glance

Graphify is excellent at telling an agent where things are. graphsnip adds the step after: hand over just that code, stop re-sending code the agent already has, and measure what it saved. Baseline here is deliberately realistic: grep the question's terms and read the top 8 matching files in full. It is far less than "read the whole repo".

Try it

Interactive explorer. Pick a layer, move the sliders (questions per day, price per million tokens, how many questions go to a cheap model) and watch the monthly numbers change. Starts from the measured Flask and Express results.

• Open docs/explorer.html in a browser (download it, it is one self-contained file), or
• publish it for your team with GitHub Pages: Settings → Pages → Deploy from branch → main / docs, then visit https://naubadnithin7.github.io/codegraf/explorer.html.

Quick start

pipx install graphsnip            # or: pipx install git+https://github.com/naubadnithin7/codegraf
cd your-repo
graphsnip init                    # build graph, wire up Claude Code / Copilot / Codex, write the dashboard
graphsnip report --open           # savings dashboard (grows as agents use it)

No LLM key needed. Everything runs locally: Graphify parses with tree-sitter, graphsnip slices with tree-sitter.

Want a one-command demo on any repo? graphsnip demo --open builds the graph, runs a benchmark and opens the dashboard.

What you get

How it fits together

flowchart TB
    R[your repo] --> G["Graphify<br/>tree-sitter AST → graph.json<br/>graph.html · communities"]
    G --> S
    subgraph S["graphsnip"]
        direction LR
        A["symbol slicer · context packs<br/>session dedupe · budgets"]
        B["router · hooks · shell compression"]
        C["savings ledger · dashboard"]
    end
    S --> M["MCP server<br/>gs_pack · gs_find · gs_symbol<br/>gs_impact · gs_outline · gs_route"]
    M --> CC[Claude Code]
    M --> CP[Copilot]
    M --> CX[Codex]
    S --> D[".graphsnip/dashboard.html"]

See it working

Every call, grey vs teal. Each pair is one tool call: what grep + read would have cost against what graphsnip returned (log scale), with the multiplier on top.

Same answers, a fraction of the tokens. On these questions every approach found the symbols, so the difference is what it cost to get there.

Graphify's own graph is embedded in the dashboard (and works offline). Every node is a symbol, colours are detected communities.

Slash commands

graphsnip install writes these for you:

/graphsnip how does request routing work
/graphsnip impact Flask.dispatch_request
/graphsnip savings

Model routing

graphsnip cannot switch an agent's model by itself (an MCP server has no such power). What it does is decide, steer, and account for it honestly.

flowchart LR
    T["/graphsnip task"] --> R{"gs_route<br/>wording + graph size"}
    R -- light --> L["cheap model answers<br/>(Haiku)"]
    R -- "too hard" --> E["prints: Escalating to Sonnet / Opus…"]
    E --> H["stronger subagent finishes the job"]
    L --> A[answer]
    H --> A

• Statuses. routed (running tier matched the decision), escalate, session (ran on your own model on purpose), overpowered, advisory (nobody verified which model ran). Dollars are credited only for routed.
• Routing saves dollars per token, not tokens. The token savings above come from the graph alone, and the dashboard keeps the two apart.
• Prices are editable placeholders under routing.prices in .graphsnip/config.json. Put your real ones in before showing a dollar figure. Codex model names go under routing.models.codex.

// .graphsnip/config.json
{ "routing": { "models": { "codex": { "light": "<your light model>", "standard": "<your main model>", "heavy": "<your strongest model>" } } } }

graphsnip codex "where is the auth middleware defined"      # routes, then runs codex exec -m <model>
graphsnip codex --dry-run "refactor session handling"      # print the command only

Measured A/B: real tokens and real cost

The dashboard's savings are estimates against a hypothetical baseline. To get measured numbers, run the same questions through headless Claude Code with and without graphsnip:

graphsnip ab --dry-run              # preview: how many sessions, the exact command
graphsnip ab --yes --repeats 2      # run it (spends real usage; capped at $5 total by default)
graphsnip report --open             # "Measured A/B (real runs)" card + headline KPI

• Two throwaway copies of your repo: one with graphsnip uninstalled, one with it installed. Your repo is never modified.
• Both arms are read-only, use the same model and prompt, and start a fresh session per run, in shuffled order.
• Cost and tokens are what claude -p --output-format json reports (total_cost_usd, input, cache and output tokens), so caching and every turn are included.
• Results are medians over repeats; model runs are noisy, so use --repeats 3 or more for a number you will quote.
• "Found" only checks that the expected symbols appear. The full answers are saved under .graphsnip/ab/ so you can judge quality yourself.
• Needs the claude CLI on your machine. Codex A/B is not implemented yet.

Commands

How the numbers are measured (and what they are not)

• Baseline per call. find / pack: grep the question's terms, read the top 8 matching files in full. symbol: read the whole file. impact: grep the name, read matching files (cap 10).
• Counted once. In a real session, tokens that stay in context are re-sent every turn, so true savings compound. The dashboard does not claim that (the explorer has an optional slider to show it).
• Quality is checked, not assumed. A task counts as answered only if the expected symbol appears with its source. That measures whether the right code was delivered, not whether a model's final answer was right.
• Shell savings are exact (raw vs compressed output). Token counts elsewhere are chars / 4 estimates; install graphsnip[accurate] for tiktoken.
• Your repo will differ. Savings are larger where files are large and lookups are broad. Replace the auto-generated tasks in .graphsnip/tasks.json with questions you really ask, then graphsnip bench.
• Dollars on the main dashboard are tokens × price per million input tokens, ignoring output tokens and caching: a list-price estimate. For measured dollars use graphsnip ab.

Known limits

• The hooks and the three client configs follow each tool's documented formats; the MCP server was verified against the official MCP Python client. Run graphsnip doctor and a short session in each client before relying on them.
• Symbol slicing is exact for the ~25 languages with tree-sitter grammars installed; elsewhere it falls back to indentation or brace matching.
• The graph only covers what Graphify extracts from code. Docs, PDFs and images need Graphify's semantic pass (needs an LLM key) and are not part of graphsnip's tools.
• Graphify's graph.html loads vis-network from a CDN; graphsnip caches it locally so the dashboard works offline (needs internet once).
• Model routing: Copilot cannot hand off to another model, Codex prompt files cannot pin one (use graphsnip codex), and the "measured" model mix works only for Claude Code.

Development

pip install -e ".[dev]"
pytest -q

Publishing: python -m build && twine upload dist/* (PyPI), cd npm && npm publish (thin npm wrapper that needs Python 3.10+ and pipx or uv).

License

Apache-2.0. graphsnip is a separate project that calls Graphify (also Apache-2.0) as a library; see NOTICE.