Codedict – a no-AI code index that cut my Claude Code tokens by 63%

A dictionary of your code for the AI, and a manual for you.

It reads your project once, with no AI, and hands the answer over together with the question.

Fewer turns, fewer tokens, the same correct answer.

Install · Why · How it works · Benchmark · Other AIs

One line, once per machine. It also turns codedict on in Claude Code for every project.

irm https://raw.githubusercontent.com/Marqueos/codedict/main/install.ps1 | iex

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/Marqueos/codedict/main/install.sh | sh

That's it. Open Claude Code in any git repository and ask about the code. There is nothing else to configure.

Uninstall: run ~/.codedict/venv/bin/python -m codedict setup --remove (Windows: ~.codedict\venv\Scripts\python.exe -m codedict setup --remove) and delete the ~/.codedict folder.

pip install git+https://github.com/Marqueos/codedict python -m codedict setup

Why it exists

codedict came from a practical problem: on a real project with ~250 files in TypeScript, C# and Python, Claude Code sessions kept hitting the usage limit.

We measured it, and the culprit was not the code being read but the number of turns. Every time the AI calls a tool (a grep, opening a file), Claude Code re-reads the whole context: 35 to 50 thousand tokens per turn. A simple question like "where is X and who calls it?" took 5 turns of grep and file reads. A flow question like "from the click to the result" took more than 20.

The idea was to do the search work once, with no AI, in a local index, and hand the ready answer over together with the question. The AI answers in 1 or 2 turns instead of 5 to 20.

The goal was to cut at least 55% of the tokens without losing a single answer. The measured result was −63%, with 12 out of 12 correct answers.

Cost falls less than tokens because the fixed part of each session (the context cache) is the most expensive part, and it does not go away. Full method, every round and what went wrong along the way: BENCHMARK.md.

flowchart LR C["Your code"] -->|"tree-sitter, no AI"| I[("Local index<br>.codedict/index.db")] P["Your question"] --> H{"Claude Code<br>hook"} I --> H H -->|"function, file:line,<br>callers, code"| R["AI answers<br>in 1 to 2 turns"]

Loading

Reads the code once. Finds every function, class, HTTP route and SQL table, and who calls whom. Stores it all in a local SQLite file, spending zero tokens.

Keeps itself up to date. When the project opens and after each AI edit, it re-reads only the files that changed.

Answers with the question. When you ask about the code, the hook searches the index and hands the result to the AI together with your question: the exact location, every call site, the chain up to the entry point, and the code.

Stays quiet otherwise. Prompts that are not about code ("thanks", "commit this") and / commands get nothing.

Without codedict, the AI goes: question, grep, open a file, another grep, another file, and only then answers. That is 5 to 20 turns, and each one re-reads everything.

codedict does the same step as a RAG: it fetches context and hands it to the AI before the answer. The difference is how it searches.

Because it is only a retrieval step, it works with any AI: Claude, GPT, Gemini or a local model.

For Where What it has

The AI .codedict/ai/, codedict search and the MCP server A compact map of the project and ready answers per question

You .codedict/docs/README.md A Markdown manual with Mermaid diagrams: modules, routes, tables and who calls whom

The .codedict/ folder ships with its own .gitignore, so it never clutters your repository.

Tool How to connect

Claude Code Automatic, through the installer

Cursor, Codex, Gemini CLI, OpenCode, Windsurf MCP server (codedict --root <project> mcp) plus codedict agent-snippet >> AGENTS.md

Any model, including local ones (Ollama, LiteLLM) RAG mode: codedict search "<question>" --budget 2000, then paste the output into the prompt

Step by step, with Python examples: INTEGRATION.md. Day-to-day use: GUIDE.md.

codedict search "where is the discount calculated" # start here: a ready answer codedict show Pricing.applyDiscount # card + exact lines (accepts several names) codedict callers OrderService.Save # who calls it codedict callees OrdersController.Get # what it calls codedict overview # big picture: modules, entry points, key symbols codedict map src/Billing/ # files and symbols of a module codedict routes api/orders # HTTP routes codedict tables Orders # SQL tables and who uses them codedict note Pricing.applyDiscount "Rule approved by finance" # a note that survives reindexing codedict index . # index by hand (Claude Code does it for you)

Benchmark

The test compared real Claude Code sessions with and without codedict. Everything needed to reproduce it is in bench/, and the full report is in BENCHMARK.md.

Zero-token check on public projects: a script runs the questions straight against the index, with no AI, and reports whether the first search already returns the full answer. Anyone can reproduce it:

git clone https://github.com/spf13/cobra && git -C cobra checkout adbc881 codedict index cobra python bench/answerability.py cobra bench/public/cobra.json # no tokens, ~1 second python bench/ab_test.py --a <copy-without> --b <copy-with> --tasks bench/tasks.example.json --reps 3 # real sessions (spends tokens)

Honest limits:

Python, JavaScript, TypeScript/TSX, C#, Java and Go (tree-sitter), SQL/T-SQL and Razor/Blazor (regex). Other files (.json, .csproj, .md…) are listed as files.

Questions can be in English or Portuguese: the search understands inflections in both ("parsed" finds ParseFlags, "exclusão" finds excluir).

For another language, copy a .toml from codedict/languages/ to the project's .codedict/languages/ and adjust the grammar nodes. Grammars come from tree-sitter-language-pack, which has more than 160 languages.

"What it does", without AI: manual note (codedict note) → doc comment → signature and name. Without a doc comment, the description is structural (where it is, what it calls, who calls it), not semantic.

Known limits: resolution is by name and declared type, not by a compiler; conventional MVC routes are inferred as /{Controller}/{Action}; Razor and XAML give file-level facts only.