codebase chat for Claude · Python CLI
Ask Claude about your code.
Send it less.
claude_light indexes your repository once, then answers each question with the handful of methods that matter instead of the whole tree. The parts that do not change stay in Anthropic's prompt cache, and simple lookups go to Haiku. On 40 questions across four open-source Python projects it cost $1.16 where Claude Code cost $5.81.
- Free for noncommercial use
- Python 3.12+
- Claude subscription or API key
- Embeddings run locally
> where do we retry a failed request?
… answer streams here …
> /why
Routed : claude-haiku-5-5 · effort=low · budget=1500
Retrieved 3 chunk(s), floor=60% of top:
0.712 (100%) adapters.py::send
0.604 ( 85%) retry.py::Retry.increment
0.471 ( 66%) sessions.py::Session.send✓ skeletondirectory tree and docs, cached for an hour
✓ 3 methodssent with their imports, not the 3 files
○ Haikua lookup, so not a Sonnet or Opus question
the problem
Most of what a coding session sends, the model has seen before
Rediscovered every session
A general agent starts each session knowing nothing about the repo, so it reads files through tool calls until it finds the code. Each round trip carries the context that came before it.
Whole files for one method
The answer usually lives in two or three methods. Reading the 1,500-line files they sit in pays for the other 1,400 lines on every turn of the conversation.
The big model for small questions
"Where is this called?" does not need the model you would ask to redesign the module, but a tool that always uses one model bills it at that rate anyway.
claude_light does the finding before the model is involved: the repo is indexed on your machine, each question gets only the methods that answer it, and the model is chosen by what the question needs.
how it works
Index once, retrieve per question, cache the rest
Index once
tree-sitter splits source files into one chunk per method, each keeping its imports and class header. A static embedding model indexes them in seconds; a transformer model catches up in the background. Saving a file re-indexes just that file.
Retrieve per question
Each question pulls only the chunks that clear two floors: a similarity of 0.35, and 60% of the best hit. The effort level sets the budget, from 1,500 tokens for a lookup to 9,000 for a design question.
Cache what does not move
The directory tree and your Markdown docs form a system prompt cached for an hour. Three cache breakpoints mean a follow-up about the same code pays full price only for the new question.
benchmark
Same 10 questions per repo, both tools, real API bills
Claude Code ran each question in a fresh claude --print session using its
own tools to find files. claude_light used its index, cache and router.
| Repository | Size | Claude Code | claude_light | Saved |
|---|---|---|---|---|
psf/requests 2.31.0 | 108K tokens | $0.91 | $0.23 | 75% |
pallets/flask 3.0.0 | 144K tokens | $1.62 | $0.17 | 89% |
encode/httpx 0.25.2 | 191K tokens | $1.75 | $0.45 | 74% |
bottlepy/bottle 0.13.2 | 92K tokens | $1.52 | $0.30 | 80% |
| Total, 40 questions | $5.81 | $1.16 | 80% |
Live API runs on 2026-03-23. Models and prices have changed since, so treat the
ratio as the result, not the dollar amounts. The script ships in the repository
(tests/benchmarks/benchmark_claude_code.py) and the
methodology
explains what each column counts. Claude Code is a general agent and does far more than
answer questions about one repo; this compares the job they share.
features
Built for asking, and for the edits that follow
Haiku for lookups, Opus for design
A router scores each question and picks Haiku, Sonnet or Opus with a matching
retrieval budget. /why shows the model, the budget and every chunk that
was sent, with its score.
Changes you approve, commits you can undo
Proposed edits are lint-checked and shown as a diff before anything is written.
Approved edits are committed with a Claude: prefix, and /undo
reverts the last one without touching your own work.
Your subscription or your API key
With a Claude Pro or Team subscription it uses the Claude CLI's login. With an API key it pays per token, and a heartbeat checks every 30 seconds to keep the cache warm through idle spells longer than 4 minutes.
No shell commands unless you allow them
The agent runs nothing by default. --allow-command opens specific prefixes,
such as your test runner. Permission rules, hooks and MCP servers inside the repo are
ignored, so a cloned repo cannot grant itself commands.
Conversations that stay small
Only the last 6 turns are resent. /compact replaces the conversation
with a summary, and /cost shows tokens, cache hit rate and spend for the
session.
Savings a build checks
CI fails a change that raises token cost or lowers retrieval quality against committed baselines. The retrieval and routing benchmarks run offline, with no API key and no spend.
licensing
Free for noncommercial use, licensed for company use
claude_light is source-available, not open source. The same package does both jobs; what a licence buys is the right to use it commercially.
Noncommercial
Free
No key and no signup. Your Claude usage is billed by Anthropic as usual.
- Personal projects, hobby work and private study
- Research and teaching
- Charities, schools, public research bodies and government
- Every feature, nothing held back
Commercial
Checkout opening soon
Online licences are not on sale yet. Using claude_light for a for-profit company's work needs one, so until checkout opens, email us and we will license you directly.
- Company machines and CI
- Invoice or purchase order on request
- Evaluating it at work first is fine
Which one applies to you. The PolyForm Noncommercial License 1.0.0 does not grant commercial use. If claude_light runs anywhere in a for-profit organisation's work you need a commercial licence, including on a single developer's laptop.
Commercial tiers
The developer count is the number of developers who use claude_light. Billed yearly.
| Developers | Price per year | |
|---|---|---|
| 1 to 9 | ||
| 10 to 49 | ||
| 50 to 199 | ||
| 200+ |
Checkout is handled by Paddle, our merchant of record, which acts as the seller of record and handles VAT and sales tax. Prices exclude tax; it is added at checkout, and shown in your local currency where Paddle supports it.
install
Install, sign in, ask
pipx install git+https://github.com/PIsberg/claude_light.git
# or
uv tool install git+https://github.com/PIsberg/claude_light.gitclaude auth login # Claude Pro or Team subscription
export ANTHROPIC_API_KEY=sk-ant-... # or pay per tokenclaude-light # interactive
claude-light "what does OrderService do?" # one-shot, answer on stdoutThe first install pulls in PyTorch through sentence-transformers, about 1.5 GB. The macOS, Linux and Windows installers, the configuration options and the optional LLMLingua compression are in the README.
faq
Questions
Does it replace Claude Code?
No. It is built for one job: questions about a repository and the edits that follow. With a subscription, each turn runs the Claude CLI's own agent with the retrieved code already in its context, so it starts from the right methods instead of searching for them.
What leaves my machine?
What goes to Anthropic: the directory tree and your Markdown files, the chunks retrieved
for the question, the question itself and the recent turns. Indexing and embeddings run
locally, and the index is stored in .claude_light_cache in your project.
Which languages?
Per-method chunking covers Java, Python, Go, Rust, JavaScript and TypeScript. Without the tree-sitter grammars installed, files are indexed whole.
Do I need a GPU?
No. On a CPU the static model indexes claude_light's own 1,400 chunks in about 2 seconds, so the first question already has context. The transformer model takes about 380 seconds on the same chunks and runs in the background; its vectors are cached.
Is it affiliated with Anthropic?
No. claude_light is an independent tool from Deversity that calls Anthropic's API and the Claude CLI. Your Claude usage is billed by Anthropic under your own account.
License?
PolyForm Noncommercial 1.0.0: free for personal, study, research and other noncommercial use. Company use needs a commercial licence; online checkout is not open yet, so email us in the meantime.
Stop paying for the same context twice
One install, one sign-in, run it from your project root. Free for noncommercial use.