fittok 0.3.1

MCP server that retrieves the most relevant source code for a query, within a token budget

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.

---

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).
2. slurp — scores every node against the question with **semantic embeddings
   • TF-IDF + PageRank**, then selects only the genuinely relevant nodes via a relevance cliff (no budget-padding with noise).
3. readable output — returns the actual source code of those nodes, top-ranked in full and the supporting tail as signatures, trimmed to a budget. The model answers directly from it.

Note: an earlier design compressed the slice with LLMLingua, but that produced unreadable token-salad the model ignored (then re-read the files). fittok returns real, readable code instead. LLMLingua remains available only as the standalone compress_context tool.

Graphs and embeddings are cached on disk (~/.cache/fittok), keyed by content — so after a code change only the changed functions re-embed.

---

Install & use

fittok runs through uv — one tool for everything below, with no manual pip install. Install it once:

brew install uv                                  # macOS
# or any OS:  curl -LsSf https://astral.sh/uv/install.sh | sh

As an MCP server (recommended — Claude Code / Cursor / Windsurf)

Claude Code — one command:

claude mcp add fittok -- uvx fittok      # add -s user to enable it in every project

Restart Claude Code, then run /mcp to confirm fittok shows connected.

Cursor / Windsurf / any MCP client — add to its MCP config:

{ "mcpServers": { "fittok": { "command": "uvx", "args": ["fittok"] } } }

Then ask codebase questions normally. To make fittok trigger without mentioning it, add one line to your client's CLAUDE.md:

"For any codebase question, call fittok first and answer from its output."

As a CLI (no MCP, no install — uvx fetches + runs it)

uvx fittok index <repo>                       # optional one-time pre-warm
uvx fittok query <repo> "how does auth work"  # prints the relevant code slice

As a library

uv add fittok            # in a uv project   (or:  uv pip install fittok  in a venv)

from fittok import optimize
result = optimize("/path/to/repo", "how does authentication work")
print(result["optimized_context"])

First query on a repo auto-indexes (~15s once, cached); after that it's instant.

---

Token savings — honest numbers

fittok cuts the input/exploration cost of a codebase question. On a real Next.js/TS repo (~5k functions) it returns a ~1.5–3.5k-token slice instead of the model reading 15–20k+ tokens of files — an ~80–90% reduction on input, deterministic and reported in the tool's savings footer.

How to measure it honestly:

• ✅ Use the savings footer (e.g. 84% — 2,494 vs 15,631 tokens) or your API bill (total tokens — which counts the subagent crawls fittok avoids).
• ⚠️ Do not judge by Claude Code's /context "Messages" number — it excludes subagent tokens and is dominated by the model's own reasoning, which fittok doesn't touch. On thorough models the real saving (e.g. ~84k → ~27k total tokens, by avoiding an Explore subagent) is invisible there but clear on the bill.

Where it shines: broad / multi-file questions, large files, unfamiliar repos, and thorough models that would otherwise explore heavily. On a tiny question a capable model can answer from one small file, so the win is marginal there.

---

Configuration (env vars)

Variable	Default	Purpose
FITTOK_SHOW_SAVINGS	false	Append a 🪙 saved X% footer to answers
FITTOK_EMBED_MODEL	all-MiniLM-L6-v2	Embedding model
FITTOK_DEVICE	auto	auto / cuda / mps / cpu
FITTOK_CACHE_DIR	~/.cache/fittok	Cache location

Requirements

Python ≥ 3.10. First run downloads a ~90 MB embedding model. Optional extras: uv pip install "fittok[ui]" (graph visualizer), "fittok[gpu]" (torch/CUDA).

License

MIT.