Codedict cuts Claude Code tokens 63%, but cost only 26%

codedict, a free MIT-licensed tool described in its README on GitHub on November 1, parses a repository once with tree-sitter and no AI. A Claude Code hook then hands over the matching function, its callers and its code along with each question. In its author’s benchmark on one private project, that cut tokens by 63% across 12 real sessions per side, and 12 of 12 answers were correct with and without it. Questions that name code got answered in 1 or 2 turns instead of 5 to 20, yet the bill fell only 26%, from $5.76 to $4.27, because writing context to the cache is the most expensive part of each session and it doesn’t go away.

One line, every project

Installing takes one command per machine: curl -fsSL https://raw.githubusercontent.com/Marqueos/codedict/main/install.sh | sh on macOS and Linux, or irm https://raw.githubusercontent.com/Marqueos/codedict/main/install.ps1 | iex in PowerShell. It needs Python 3.11 or newer, installs into ~/.codedict, needs no admin rights and doesn’t touch PATH or the system Python. It also writes three hooks to ~/.claude/settings.json and a short instruction to ~/.claude/CLAUDE.md, and keeps the previous settings file as settings.json.codedict-bak. From then on codedict is on in Claude Code for every project, and any git repository works with nothing to configure.

To update, run the same line again. Removing it takes ~/.codedict/venv/bin/python -m codedict setup --remove (on Windows, ~\.codedict\venv\Scripts\python.exe -m codedict setup --remove) and then deleting the ~/.codedict folder.

Each project gets its index in .codedict/index.db, a local SQLite file, inside a .codedict/ folder that comes with its own .gitignore. The index is refreshed when the project opens and after each AI edit, and only files whose sha256 hash changed get re-read. The same folder holds a Markdown manual for people, .codedict/docs/README.md, with Mermaid diagrams of modules, routes, tables and who calls whom. In the terminal, codedict search "where is the discount calculated" returns a ready answer, codedict callers OrderService.Save lists call sites, and codedict note attaches a note to a symbol that survives reindexing.

Fewer turns, same cache floor

The tool came out of a real project of about 250 files in TypeScript, C# and Python, where Claude Code sessions kept hitting the usage limit. When the author measured it, the problem was the number of turns, more than the code being read. Every tool call, a grep or a file open, makes Claude Code re-read the whole context, which there came to 35,000 to 50,000 tokens a turn. A question like “where is X and who calls it?” took five turns, and a flow question, “from the click to the result”, took more than 20.

In the benchmark, turns fell from 138 to 34 (−75%) and tokens from 4,543,176 to 1,666,033. The money moved much less: $1.49 saved over 12 sessions, or about 12 cents a session. The author’s explanation is that every Claude Code session carries a fixed cost of about 37,000 tokens per turn, and that codedict cuts how many turns there are but not that floor, while writing to the cache is the most expensive kind of token. Shrinking the floor itself takes a different tool. On one machine in October, a single built-in Claude Code tool weighed 11,402 tokens of a 47,700-token first request.

The test used two identical copies of the same private project. Only copy B had the index and the codedict instruction, and neither had Claude memory or any file with the answers. Both sides got the same prompt, the same model and the same read-only tools. Each task ran three times per side and the median was reported, since the same task varied by up to 45% between sessions. An answer counted as correct if it named the expected functions and files, and that check was automatic. The headline round was the default install with the hook, four tasks with three sessions each. Two more rounds used the instruction alone, without the hook: flow questions came in at −52% total with 6/6 correct, and short searches at −51% with 30/30.

When the hook stays quiet

codedict searches by exact names and the code’s real call links. A vague question such as “is the app any good?” gives it no name to search for, so the hook sends nothing and Claude Code works as it would without it. Prompts that aren’t about code (“thanks”, “commit this”) and slash commands get nothing either.

Calls are resolved without a compiler, by name and declared type, and each link is marked as high, medium or low confidence. Conventional MVC routes are inferred as /{Controller}/{Action}, and Razor and XAML only give file-level facts. If a symbol has no doc comment and no manual note, its description is structural: where it lives, what it calls and who calls it.

Python, JavaScript, TypeScript/TSX, C#, Java and Go are parsed with tree-sitter, and SQL/T-SQL and Razor/Blazor with regular expressions. Other files, such as .json or .csproj, are only listed. Questions can be in English or Portuguese, and the search handles inflections in both (“parsed” finds ParseFlags). To add a programming language, copy a .toml from codedict/languages/ into the project’s .codedict/languages/ and adjust the grammar nodes. The grammars come from tree-sitter-language-pack, which covers more than 160 languages.

Outside Claude Code

Only Claude Code gets the hook set up automatically, and every measured session was a Claude Code session. Cursor, Codex, Gemini CLI, OpenCode and Windsurf connect through an MCP server, codedict --root <project> mcp, together with codedict agent-snippet >> AGENTS.md. For any other model, including local ones behind Ollama or LiteLLM, codedict search "<question>" --budget 2000 prints context you paste into the prompt.

On public code, a script sends questions straight to the index with no AI and reports whether the first search already returns the full answer: it did for 3 of 4 questions on psf/requests and 3 of 3 on spf13/cobra. The cobra check is the cheapest part to rerun. Clone spf13/cobra, check out adbc881, run codedict index cobra, then python bench/answerability.py cobra bench/public/cobra.json. It spends no tokens and takes about a second, while the paid A/B run, bench/ab_test.py with --reps 3, runs real sessions.