fittok

Retrieve only the relevant source code for a question — instead of the model reading whole files — so an LLM answers codebase questions on a small, focused slice of context. Less input = fewer tokens, lower cost, faster answers.

Works three ways from one install: an MCP server, a CLI, and a Python library — plus a Claude Code plugin that injects context automatically.

📖 Full command reference → docs/HANDBOOK.md

mcp-name: io.github.likhithreddy/fittok

How it works

codebase ──▶ graphify ──▶ slurp ──▶ readable slice ──▶ LLM answers
             (parse)      (select)   (trim to budget)

1. graphify — parses the repo with tree-sitter into a knowledge graph of functions / classes / methods (Python, JS, JSX, TS, TSX, Java, Go, Rust). Supports multi-language call/import/reference edges.

2. slurp — scores every node against the question using a 4-signal hybrid:

   • Semantic embeddings (all-MiniLM-L6-v2) — meaning-based matching
   • Content-BM25 (with camelCase/snake_case splitting) — keyword matching
   • Summary-BM25 (node name + file + callers + callees) — structural matching
   • PageRank — graph centrality / hub detection

   Signals are fused via Reciprocal Rank Fusion (RRF) — rank-based, no score calibration issues. Nodes are selected via round-robin directory interleaving (guarantees facet coverage on multi-aspect queries — one node from each code area before any gets a second) with a per-node token cap (25% of budget, so large components don't crowd out smaller functions). A relevance cliff (semantic OR BM25 OR summary-BM25 threshold) excludes noise.

3. readable output — returns the actual source code of selected nodes, plus a codebase map (table of contents with docstrings, inspired by Karpathy's LLM Wiki / Google's OKF) so the model can route follow-up calls precisely. The model answers directly from it — no file reads needed.

As you edit, a file watcher (auto-started on first query) updates the graph incrementally — only changed files are re-parsed and merged, and only changed functions re-embed. Graphs and embeddings are cached on disk (~/.cache/fittok). Set FITTOK_AUTOWATCH=false to disable the watcher, in which case an edit triggers a full re-parse on the next query.

Getting the best results (and known limitations)

Ask focused questions

fittok ranks code against your question using a 4-signal hybrid (semantic + BM25 + structural + PageRank, fused via RRF) with round-robin directory diversity — so multi-facet questions surface code from multiple areas (UI, server, database) instead of clustering in one dominant area. It's most accurate with focused, specific questions — ideally one concern each, and naming the function/component/route when you can. Multi-facet questions are supported via decomposition (the tool description tells the model to call once per aspect) and the codebase map (a table of contents prepended to every response).

• ✅ "How does runSandboxQuery execute and isolate a SQL query?" → surfaces the exact function + its isolation code.
• ✅ "How does the querydle client submit a query and render results?" → surfaces the UI component.
• ✅ "Trace the full lifecycle: UI submission, sandbox execution, data isolation" → decomposition + round-robin diversity covers multiple facets; the codebase map routes the model to any missed files.

Rule of thumb: one concern per question (or 2–3 facets max). For "explain the whole feature," split it into a few focused questions instead of one mega-query.

Known limitations

• GitHub Copilot Chat truncates large MCP outputs (the big one). Copilot caches MCP tool results above ~7 KB to a content.json file, where the entire markdown

... View full README on GitHub