slimdex-mcp

Your agent reads a 900-line file to change one function — then pays for that file again on every turn that follows. The whole conversation is re-sent each time, so an early read isn't a one-time cost. It's rent.

Slimdex is a local MCP server that gives coding agents narrow retrieval instead: a file's outline, one symbol's body, who calls it, what breaks if it changes — and memory that survives the session, so the next chat starts informed rather than re-deriving the repo from zero.

claude mcp add slimdex -- npx -y slimdex-mcp

~50% fewer tokens in day-to-day use — ~55–60% on navigation-heavy work, ~45% on output-heavy work, and 85–90% on the worst case it was built for (one 6,200-line file, explored through a skeleton and 12 symbol bodies instead of four full reads).

Status: 1.1.0, on npm and in the MCP Registry. Those numbers are self-measured on the repos it has been run against, single sessions, not independently validated — and stats counts characters, not tokens. Read What's actually verified before relying on it.

The retrieval guidance below also ships in the server's MCP instructions, so clients inject it into the model's context automatically.

Recommended agent flow

brief first, at the very start of a session — one call that reports what the repo is, where recent sessions were digging, and which saved conclusions still match the code (stale ones flagged), so a fresh chat starts informed instead of blank. Then get_context("Foo") to answer "what is this, who calls it, what does it depend on" in one response. To understand a whole area rather than one symbol, context_pack("how does auth work") runs the entire exploration server-side and hands back a single bounded bundle — the relevant symbols, how they connect, and the top bodies — so you spend one call and one transcript entry instead of ten. Don't know the name, only what it does? — search_intent("parse the config file") ranks symbols by intent with BM25, no embeddings. Drop to get_symbol_context for one body (it flags itself if the file drifted from the index, so you don't re-read to check), get_file_skeleton for a file's shape, and read_lines when you need exact source. Before editing a symbol, find_tests on it to see what covers it; to rewrite a whole function, replace_symbol (you send only the new body — the old code isn't re-sent just to locate the edit). Use batch to bundle several lookups. Every search tool takes limit (default 20) and offset.

Response budgeting: get_context sections are opt-in via include (default: definition, signature, callers, imports — add body or dependents explicitly), callers are capped by callerLimit, and the response is bounded by maxChars (default 12,000). Every cap that trips prints an explicit notice (showing 3 of 68, truncated at maxChars=...) rather than dropping data silently. get_symbol_context caps its span with maxLines the same way, and memory_list returns the newest 50 facts unless told otherwise, as ~150-char previews rather than whole bodies (memory_get ids:[...] expands them, full:true dumps everything). On an 18-fact store that is the difference between ~4,100 and ~18,600 chars in the call every session opens with.

Config: <root>/.slimdex.json (optional)

{
  "ignoreDirs": ["fixtures", "backend/src/main/resources/static/assets"],
  "extensions": [".astro", ".vue"],
  "suffixes": [".stories.mdx"],
  "exclude": ["generated/", "legacy/vendor"],
  "maxFileBytes": 2000000
}

suffixes matches a filename ending, for file types an extension can't identify. Salesforce metadata sidecars ship as a built-in: AccountSvc.cls-meta.xml, panel.js-meta.xml and Account.object-meta.xml are indexed, while pom.xml, web.xml and manifest/package.xml are not — adding .xml to extensions would have pulled in every config tree in the repo. Suffix-matched files are indexed for search and read reach, not symbols.

Merged on top of the built-in ignore list (node_modules, dist, .venv, .svelte-kit, Pods, .pytest_cache, …). An ignoreDirs entry is either a bare name, matching any directory so called at any depth, or a path containing /, anchored at the repo root and respecting directory boundaries (src/gen will not also ignore src/generated). index_repo echoes what it loaded and warns about unknown keys, wrong types, or invalid JSON, so a typo'd config isn't silently indistinguishable from none.

Build output usually needs no config at all. Beyond the directory list, any file whose lines run past ~5,000 characters is treated as minified build output and left out of the index — bundlers strip newlines, and hand-written source doesn't look like that. This catches what a name list structurally cannot: a hash-named bundle (index-B7xK2p9q.js) inside a directory called assets. assets, public and static are deliberately not ignored by name, because real source lives in them; index_repo reports the count as skipped(minified build output): N.

How the token saving works

There's no compression trick. The saving is behavioral: these tools let an agent retrieve outlines, ranges, and locations instead of whole files, and the persistent index means repeat lookups hit a cached query rather than a re-read.

Two later sessions, run by different models on different repo shapes, added real-world numbers to the original report:

Multi-file web app, bug-fix session (GPT-5.3-Codex). 19 credits reported with slimdex; the model's own estimate for the same scope without it: 45–70 credits. Math: 19/45 → 19/70 ≈ 58–73% cheaper. The counterfactual is the model's estimate, not a measured A/B — directional.

Single giant file (folio-app: one 6,200-line, 313 KB app.js). Slimdex's own stats: ~34,000 chars across 8 calls ≈ 9–10k tokens — one skeleton (213 signatures), then bodies of only ~12 relevant functions, 9 of them fetched in a single get_symbol_context names:[...] call. The naive path: 313 KB ≈ 78–85k tokens across 3–4 forced full reads. Math: ~10k vs ~80k ≈ ~70k tokens saved, an 85–90% reduction on exploration. The bug's diagnosis (an export path with no matching import path) was visible from the skeleton's signatures before a single body was opened.

Together they sketch the scaling law: the saving scales with how much irrelevant code the naive path would drag in. One giant file is the best case; a normal repo lands around half to two-thirds cheaper; a repo of tiny files breaks even. Same standing caveats as everything here: stats count chars, not tokens (÷3.5–4), and single sessions are evidence, not benchmarks.