Metadata-Version: 2.4
Name: lighten
Version: 0.3.1
Summary: Keep Claude Code conversations light: earlier guided compaction, memory across sessions, and shorter tool output, so you use fewer tokens.
Keywords: claude-code,claude,tokens,context,compaction,hooks,llm,cost
Author: sukumarlightningleap
Author-email: sukumarlightningleap <sukumar@lightningleap.org>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Dist: fastapi>=0.115,<1 ; extra == 'server'
Requires-Dist: pydantic>=2.10,<3 ; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.34,<1 ; extra == 'server'
Requires-Python: >=3.10
Provides-Extra: server
Description-Content-Type: text/markdown

# 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.

```bash
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. **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](https://docs.astral.sh/uv/)
(or pipx). Python 3.10+ is fetched automatically by uv if needed.

```bash
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

```bash
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):

```bash
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

```bash
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):

```json
{
  "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 output
- `memory`: compaction guidance and memory notes
- `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

```bash
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 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.
