Skip to main content

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

  1. 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.
  2. 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.
  3. 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.
  4. Tells you when it acts. A one-line message appears only when something happens (Lighten · compacted 169k → 13k, memory kept), and Claude Code's status area (terminal and editor panel) shows context 84k / compacts at 167k · 5-hour 32% · 2 compactions today.
  5. Shows you the numbers. lighten audit reads 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. It also adds a small Claude Code plugin (with Claude Code's own claude plugin commands) that shows Lighten's status line and compaction messages. If the plugin can't be added, Lighten uses a terminal-only status line instead, and never replaces one you set.

Update with uv tool upgrade lighten.

See what it saves

lighten audit

It shows a short summary of what Lighten changed for you, before vs with Lighten:

  • how big the conversation Claude re-reads each reply is
  • tokens per message
  • plan usage per message (tokens weighted by model price, so cached re-reads count least; before = 100)
  • roughly how much more work your 5-hour and weekly limits now fit

Each reply counts as "with Lighten" only if Lighten was running in that session at the time, so a session you resumed after installing is split correctly. lighten audit --details shows the full report: cost estimates, time per message, session length, compactions, shortened outputs, memory notes and the plan-limit history.

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 install --no-statusline           # no status line and no plugin
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,
  "notify": true,
  "inject_on_startup": true,
  "startup_max_age_hours": 24,
  "max_inject_chars": 4000,
  "output_retention_days": 7
}
  • distill: shorten noisy command output
  • memory: compaction guidance and memory notes
  • notify: show a one-line Lighten · … message when Lighten acts
  • inject_on_startup: give Claude a note from the previous session when you start Claude Code in the same project (only if it was within startup_max_age_hours)

Uninstall

lighten uninstall           # removes the hooks, plugin and status line, 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 summary
  • outputs/: full copies of shortened outputs, deleted after 7 days
  • logs/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.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lighten 0.3.3
File Size Uploaded Provenance Actions
lighten-0.3.3.tar.gz 52.7 kB Without provenance Details for lighten-0.3.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lighten 0.3.3
File Interpreter ABI Platform Actions
lighten-0.3.3-py3-none-any.whl Python 3 none any Details for lighten-0.3.3-py3-none-any.whl

Total release size: 122.9 kB

Release files / lighten-0.3.3.tar.gz

Download URL lighten-0.3.3.tar.gz
Size 52.7 kB
Tags Source
SHA-256 checksum
How to use checksums
a68afb8f66c1e0aff55e6eacbe0655d0af3d1c4917bcdc65e398f8480ac83074
BLAKE2b-256 checksum
How to use checksums
e11e03b0fbf0a45646bcd04f5534d8326131b1c691b74850b652d739344c97a7
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}

Release files / lighten-0.3.3-py3-none-any.whl

Download URL lighten-0.3.3-py3-none-any.whl
Size 70.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9749ddb953481fe192d208dc69fbfbef527f7b0602e338bce04ff622466a9e77
BLAKE2b-256 checksum
How to use checksums
442b69f6886e3825d39fea09f673970d9f3aaec40b3e2f13044a320d88324e08
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.3

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page