Lighten — use fewer tokens in Claude Code
Every time Claude replies, it re-reads the whole conversation. Long conversations make every reply expensive, and they burn through your usage limits. Lighten keeps conversations light without losing the thread.
uv tool install lighten
lighten install
What it does
- Compacts earlier, and better. Claude Code's auto-compaction is set to start at a 200k-token conversation (instead of near 1M), and Lighten tells the summary what to keep: your goal, decisions, changed files, unresolved errors and next steps.
- Remembers. Lighten keeps a small log of what happened (your
requests, files changed, commands that are still failing). After a
compaction, after
/clear, or in a new session in the same project, it hands Claude a short note so you can start fresh without losing your place. - Shortens noisy command output. Passing-test lists, install and build progress are removed before Claude sees them. Errors, warnings and anything unrecognised are always kept. The full output is saved on your machine, and Claude is told where.
- Shows you the numbers.
lighten auditreads your local Claude Code history and shows where your usage goes, before and with Lighten.
Everything runs on your machine. Nothing is sent anywhere.
Install
You need Claude Code 2.1.121 or newer and uv (or pipx). Python 3.10+ is fetched automatically by uv if needed.
uv tool install lighten # or: pipx install lighten
lighten install
lighten status # should say "Hook self-test: OK"
Then restart Claude Code (or start a new session).
lighten install edits ~/.claude/settings.json. It makes a backup
first, keeps all your existing settings and hooks, and can be run twice
safely. If you already set autoCompactWindow, Lighten leaves it alone.
Update with uv tool upgrade lighten.
See what it saves
lighten audit
This compares your sessions before and with Lighten, with a change column:
- average conversation size and tokens per message
- cost per message (an API-price estimate; on a Pro/Max plan read it as usage)
- how much came from very long conversations (over 200k tokens)
- time per message and average session length
- compactions, shortened outputs and memory notes
It also shows your plan limit over time (weekly and 5-hour %, from
Claude Code's /usage). Claude Code keeps no history of these, so Lighten
saves a snapshot when you install it and every time you run
lighten audit. Reading /usage uses none of your plan.
Sessions in temporary folders (experiments, scripts) are left out; add
--include-temp to count them. Add --no-usage to skip the /usage
snapshot.
In our own long-session test, Lighten used about 25% less of the 5-hour limit for the same work (79% fewer tokens), with the same results. Your numbers depend on how long your sessions get: short sessions that never reach 200k tokens see little change.
To share your results (for example with the Lighten team):
lighten audit --share lighten-report.json
The file contains numbers only: no code, file paths, prompts or commands. Open it and check before you send it.
Options
lighten install --compact-window 300000 # compact later (150,000 – 1,000,000)
lighten install --no-compact-window # don't touch auto-compaction
lighten install --force # replace an autoCompactWindow you set
LIGHTEN_DISABLED=1 claude # run one session without Lighten
~/.lighten/config.json (every key optional; these are the defaults):
{
"enabled": true,
"distill": true,
"memory": true,
"inject_on_startup": true,
"startup_max_age_hours": 24,
"max_inject_chars": 4000,
"output_retention_days": 7
}
distill: shorten noisy command outputmemory: compaction guidance and memory notesinject_on_startup: give Claude a note from the previous session when you start Claude Code in the same project (only if it was withinstartup_max_age_hours)
Uninstall
lighten uninstall # removes the hooks, restores your compaction setting
lighten uninstall --purge # ...and deletes ~/.lighten
uv tool uninstall lighten
What is stored, and where
All in ~/.lighten (or $LIGHTEN_HOME), never uploaded:
projects/<project>/sessions/*.jsonl: per-session log (your requests, changed file paths, commands, what was shortened)projects/<project>/summaries/*.md: the last compaction summaryoutputs/: full copies of shortened outputs, deleted after 7 dayslogs/errors.log: hook errors (hooks never interrupt Claude Code)usage.jsonl: your plan-limit snapshots (percentages and times)
Known limits
- Failing commands are not shortened. Claude Code does not let hooks rewrite the output of a command that failed, so failing test output reaches Claude in full.
- File views are never touched (
cat,sed,head,git diff, ...). If you mostly read code, the savings come from compaction and memory. - Earlier compaction is a trade-off. Each compaction costs one summary call and can lose detail. The window can't be set below 150,000 tokens: sessions already start at ~40k, and a smaller window would compact over and over.
- Tokens and plan limit are not the same. Your plan counts re-read (cached) tokens as much cheaper than new work, and re-reading is what Lighten cuts most. So the token saving is larger than the limit saving.
- A note from the previous session (up to ~1k tokens) is added when you start Claude Code in a project you used in the last 24 hours.
- Tested on Linux with Claude Code 2.1.319. macOS should work; Windows is untested.
Upgrading from "trippy"
Lighten was called Trippy in early tests. Install Lighten and run
lighten install; it removes the old Trippy hooks automatically. Then
uv tool uninstall trippy. Old data in ~/.trippy can be deleted.
License
Lighten is free to install and use, but it is not open source.
You may not copy, modify, redistribute or resell it. The full terms are in
the LICENSE file included with the package.
Questions or problems: email the author (address on the PyPI page).
Lighten is an independent project and is not affiliated with or endorsed by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.
Metadata
Release files for lighten 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lighten-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for lighten-0.3.1-py3-none-any.whl |
Release files / lighten-0.3.1-py3-none-any.whl
| Download URL | lighten-0.3.1-py3-none-any.whl |
|---|---|
| Size | 59.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d94360a0dd2d09bc964f2da345ed8801e310419423cc29645faf167042e26328
|
|
BLAKE2b-256 checksum How to use checksums |
9ed91df2338cc765a679ec157800331439701a861224a34d51a86af5961ee08c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for lighten 0.3.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.