graphsnip

A token-saving layer on top of Graphify.

Graphify turns a codebase into a knowledge graph (tree-sitter, no LLM, runs locally). graphsnip uses that graph to give coding agents exactly the code they need instead of whole files, and then proves the savings with an honest baseline and a dashboard you can put on a projector.

Works with Claude Code, GitHub Copilot (VS Code / CLI) and Codex.

        your repo ──► Graphify (AST → graph.json, graph.html, communities)
                          │
                          ▼
   ┌───────────────────── graphsnip ─────────────────────┐
   │  symbol slicer  ·  context packs  ·  session dedupe  │
   │  budgeted tools ·  hooks          ·  shell compressor│
   │  savings ledger (honest baseline) ·  dashboard       │
   └──────────────┬───────────────────────────┬──────────┘
                  ▼                           ▼
     MCP server (gs_pack, gs_symbol, …)    .graphsnip/dashboard.html
     Claude Code · Copilot · Codex         (+ Graphify's graph.html embedded)

Demo in three commands

pipx install graphsnip          # or: uvx graphsnip …   (see "Install")
cd your-repo
graphsnip demo --open           # graph → benchmark → dashboard

Then wire it into your agents and watch live savings land in the same dashboard:

graphsnip init                  # graph + MCP + hooks + guidance for claude, copilot, codex
graphsnip report --open         # refresh the dashboard from real agent usage

What Graphify gives you vs. what graphsnip adds

Measured results

Same eight questions per repo, priced as tokens an agent would put in context. Baseline = grep the question's terms, read the top 8 matching files in full (what an agent does with no graph). "Graphify + read" = Graphify query, then reading the whole files its top hits point to. Token counts use the chars/4 estimate (install graphsnip[accurate] for tiktoken).

Graphify's bare query is cheaper still (about 13k and 18k tokens across the eight tasks) but returns a map with no source code, so the agent still has to read files afterwards. graphsnip returns the map and the code in the same step. A task counts as answered only if the expected symbol appears with its source.

Reproduce: graphsnip bench (tasks live in .graphsnip/tasks.json; replace them with your own questions).

Install

pipx install graphsnip            # recommended
# or
uvx graphsnip init                # run without installing
# or
npx graphsnip init                # thin wrapper, needs Python 3.10+ and pipx/uv

Requires Python 3.10+. Graphify is installed as a dependency (graphifyy).

Commands

Every query command prints ~N tokens returned vs ~M for grep+read → saved P% to stderr. That is the number to show live.

MCP tools

The server is a small dependency-free stdio JSON-RPC implementation (it does not depend on the MCP SDK's changing API). It auto-refreshes a stale graph and records every call in .graphsnip/ledger.jsonl.

What install writes

Everything is idempotent (run it twice, nothing changes) and reversible (graphsnip uninstall). Your existing content is preserved: text files get a marked block, JSON is merged.

Slash command usage: /graphsnip how does request routing work, /graphsnip impact Flask.dispatch_request, /graphsnip savings. Re-run graphsnip install after upgrading to get the commands.

Flags: --allow-tools pre-approves the read-only tools in Claude Code, --portable writes bare graphsnip instead of this machine's absolute path (use it before committing the configs), --strict sets hook mode to strict.

Hooks (Claude Code)

Fail-open: any error means "do nothing". Configure in .graphsnip/config.json (or GRAPHSNIP_MODE).

shell_filter: true additionally rewrites noisy test/build commands to run through graphsnip run. It is off by default because the rewrite returns an allow decision, which skips the permission prompt; it is limited to an allow-list and never touches pipelines or chained commands. POSIX shells only.

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). Deliberately far below "read the whole repo", the figure Graphify's own benchmark compares against.
• 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.
• Shell savings are exact (raw vs compressed output), not estimated.
• Quality is checked, not assumed (see answered above).
• Cost is tokens saved × price per million input tokens (default $3, set price_per_mtok in the config). It ignores caching discounts and output tokens.

Known limits

• Hooks and the three client configs follow each tool's documented formats, but only the MCP server was verified against a real client in development (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 / 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).

Development

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

Publishing

python -m build && twine upload dist/*          # PyPI (name `graphsnip`)
cd npm && npm publish                           # npm wrapper (name `graphsnip`)

License

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