lighten 0.3.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- lighten-0.3.2/LICENSE +35 -0
- lighten-0.3.2/PKG-INFO +221 -0
- lighten-0.3.2/README.md +191 -0
- lighten-0.3.2/pyproject.toml +65 -0
- lighten-0.3.2/pyproject.toml.orig +61 -0
- lighten-0.3.2/src/lighten/__init__.py +1 -0
- lighten-0.3.2/src/lighten/api/app.py +19 -0
- lighten-0.3.2/src/lighten/api/routes.py +35 -0
- lighten-0.3.2/src/lighten/api/schemas.py +41 -0
- lighten-0.3.2/src/lighten/audit/__init__.py +0 -0
- lighten-0.3.2/src/lighten/audit/pricing.py +111 -0
- lighten-0.3.2/src/lighten/audit/report.py +1235 -0
- lighten-0.3.2/src/lighten/audit/usage.py +193 -0
- lighten-0.3.2/src/lighten/auth/api_key.py +30 -0
- lighten-0.3.2/src/lighten/claude_plugin/.claude-plugin/marketplace.json +1 -0
- lighten-0.3.2/src/lighten/claude_plugin/.claude-plugin/plugin.json +1 -0
- lighten-0.3.2/src/lighten/claude_plugin/README.md +7 -0
- lighten-0.3.2/src/lighten/claude_plugin/hooks/hooks.json +1 -0
- lighten-0.3.2/src/lighten/claude_plugin/hooks/register.ts +129 -0
- lighten-0.3.2/src/lighten/clearing/__init__.py +0 -0
- lighten-0.3.2/src/lighten/clearing/distillers.py +491 -0
- lighten-0.3.2/src/lighten/clearing/engine.py +21 -0
- lighten-0.3.2/src/lighten/clearing/history.py +65 -0
- lighten-0.3.2/src/lighten/clearing/legacy_detector.py +545 -0
- lighten-0.3.2/src/lighten/clearing/renderer.py +195 -0
- lighten-0.3.2/src/lighten/clearing/thinking.py +250 -0
- lighten-0.3.2/src/lighten/cli/__init__.py +0 -0
- lighten-0.3.2/src/lighten/cli/main.py +537 -0
- lighten-0.3.2/src/lighten/detection/__init__.py +7 -0
- lighten-0.3.2/src/lighten/detection/tool_detector.py +42 -0
- lighten-0.3.2/src/lighten/hooks/__init__.py +0 -0
- lighten-0.3.2/src/lighten/hooks/__main__.py +84 -0
- lighten-0.3.2/src/lighten/hooks/dispatch.py +661 -0
- lighten-0.3.2/src/lighten/install/__init__.py +0 -0
- lighten-0.3.2/src/lighten/install/plugin.py +93 -0
- lighten-0.3.2/src/lighten/install/settings.py +462 -0
- lighten-0.3.2/src/lighten/integration/__init__.py +0 -0
- lighten-0.3.2/src/lighten/integration/claude_code.py +41 -0
- lighten-0.3.2/src/lighten/integration/request_adapter.py +51 -0
- lighten-0.3.2/src/lighten/integration/response_builder.py +37 -0
- lighten-0.3.2/src/lighten/memory/__init__.py +0 -0
- lighten-0.3.2/src/lighten/memory/handoff.py +319 -0
- lighten-0.3.2/src/lighten/memory/store.py +416 -0
- lighten-0.3.2/src/lighten/models/__init__.py +22 -0
- lighten-0.3.2/src/lighten/models/context.py +10 -0
- lighten-0.3.2/src/lighten/models/decision.py +27 -0
- lighten-0.3.2/src/lighten/models/tokenization.py +49 -0
- lighten-0.3.2/src/lighten/models/tool_result.py +109 -0
- lighten-0.3.2/src/lighten/pipeline/__init__.py +0 -0
- lighten-0.3.2/src/lighten/pipeline/curator.py +89 -0
- lighten-0.3.2/src/lighten/policy/__init__.py +0 -0
- lighten-0.3.2/src/lighten/policy/clearing_policy.py +257 -0
- lighten-0.3.2/src/lighten/policy/threshold.py +11 -0
- lighten-0.3.2/src/lighten/profiling/__init__.py +5 -0
- lighten-0.3.2/src/lighten/profiling/fidelity.py +27 -0
- lighten-0.3.2/src/lighten/profiling/refetchability.py +42 -0
- lighten-0.3.2/src/lighten/profiling/repetition.py +37 -0
- lighten-0.3.2/src/lighten/profiling/size.py +14 -0
- lighten-0.3.2/src/lighten/profiling/structure.py +29 -0
- lighten-0.3.2/src/lighten/profiling/tool_profiler.py +322 -0
- lighten-0.3.2/src/lighten/statusline.py +137 -0
lighten-0.3.2/LICENSE
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
Lighten — Proprietary License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 sukumarlightningleap. All rights reserved.
|
|
4
|
+
|
|
5
|
+
Lighten is proprietary software. It is not open source.
|
|
6
|
+
|
|
7
|
+
1. Permission to use. You may download, install and use Lighten free of
|
|
8
|
+
charge, for personal use and for internal use within your organisation.
|
|
9
|
+
|
|
10
|
+
2. Restrictions. Without prior written permission from the copyright
|
|
11
|
+
holder, you may not:
|
|
12
|
+
a. copy, modify, translate or create derivative works of Lighten or of
|
|
13
|
+
its source code, except as needed to install and run it;
|
|
14
|
+
b. distribute, publish, sublicense, sell, rent or lend Lighten, or offer
|
|
15
|
+
it as part of a hosted or managed service;
|
|
16
|
+
c. remove or change this notice or any other copyright notice.
|
|
17
|
+
|
|
18
|
+
3. Ownership. Lighten and all rights in it remain with the copyright
|
|
19
|
+
holder. This license gives you no rights other than those stated above.
|
|
20
|
+
|
|
21
|
+
4. Termination. Your permission ends automatically if you break these
|
|
22
|
+
terms. You must then stop using Lighten and delete all copies.
|
|
23
|
+
|
|
24
|
+
5. No warranty. LIGHTEN IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
25
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
26
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
|
|
27
|
+
|
|
28
|
+
6. Limitation of liability. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE
|
|
29
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
|
|
30
|
+
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH
|
|
31
|
+
LIGHTEN OR THE USE OF OR OTHER DEALINGS IN LIGHTEN.
|
|
32
|
+
|
|
33
|
+
Future versions of Lighten may be released under different terms.
|
|
34
|
+
|
|
35
|
+
Contact: sukumar@lightningleap.org
|
lighten-0.3.2/PKG-INFO
ADDED
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: lighten
|
|
3
|
+
Version: 0.3.2
|
|
4
|
+
Summary: Keep Claude Code conversations light: earlier guided compaction, memory across sessions, and shorter tool output, so you use fewer tokens.
|
|
5
|
+
Keywords: claude-code,claude,tokens,context,compaction,hooks,llm,cost
|
|
6
|
+
Author: sukumarlightningleap
|
|
7
|
+
Author-email: sukumarlightningleap <sukumar@lightningleap.org>
|
|
8
|
+
License-Expression: LicenseRef-Proprietary
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
14
|
+
Classifier: Operating System :: MacOS
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Topic :: Software Development
|
|
23
|
+
Classifier: Topic :: Utilities
|
|
24
|
+
Requires-Dist: fastapi>=0.115,<1 ; extra == 'server'
|
|
25
|
+
Requires-Dist: pydantic>=2.10,<3 ; extra == 'server'
|
|
26
|
+
Requires-Dist: uvicorn[standard]>=0.34,<1 ; extra == 'server'
|
|
27
|
+
Requires-Python: >=3.10
|
|
28
|
+
Provides-Extra: server
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
|
|
31
|
+
# Lighten — use fewer tokens in Claude Code
|
|
32
|
+
|
|
33
|
+
Every time Claude replies, it re-reads the whole conversation. Long
|
|
34
|
+
conversations make every reply expensive, and they burn through your
|
|
35
|
+
usage limits. Lighten keeps conversations light without losing the
|
|
36
|
+
thread.
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
uv tool install lighten
|
|
40
|
+
lighten install
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
**What it does**
|
|
44
|
+
|
|
45
|
+
1. **Compacts earlier, and better.** Claude Code's auto-compaction is set
|
|
46
|
+
to start at a 200k-token conversation (instead of near 1M), and Lighten
|
|
47
|
+
tells the summary what to keep: your goal, decisions, changed files,
|
|
48
|
+
unresolved errors and next steps.
|
|
49
|
+
2. **Remembers.** Lighten keeps a small log of what happened (your
|
|
50
|
+
requests, files changed, commands that are still failing). After a
|
|
51
|
+
compaction, after `/clear`, or in a new session in the same project,
|
|
52
|
+
it hands Claude a short note so you can start fresh without losing
|
|
53
|
+
your place.
|
|
54
|
+
3. **Shortens noisy command output.** Passing-test lists, install and
|
|
55
|
+
build progress are removed *before* Claude sees them. Errors,
|
|
56
|
+
warnings and anything unrecognised are always kept. The full output
|
|
57
|
+
is saved on your machine, and Claude is told where.
|
|
58
|
+
4. **Tells you when it acts.** A one-line message appears only when
|
|
59
|
+
something happens (`Lighten · compacted 169k → 13k, memory kept`), and
|
|
60
|
+
Claude Code's status area (terminal and editor panel) shows
|
|
61
|
+
`context 84k / compacts at 167k · 5-hour 32% · 2 compactions today`.
|
|
62
|
+
5. **Shows you the numbers.** `lighten audit` reads your local Claude Code
|
|
63
|
+
history and shows where your usage goes, before and with Lighten.
|
|
64
|
+
|
|
65
|
+
Everything runs on your machine. Nothing is sent anywhere.
|
|
66
|
+
|
|
67
|
+
## Install
|
|
68
|
+
|
|
69
|
+
You need Claude Code 2.1.121 or newer and [uv](https://docs.astral.sh/uv/)
|
|
70
|
+
(or pipx). Python 3.10+ is fetched automatically by uv if needed.
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
uv tool install lighten # or: pipx install lighten
|
|
74
|
+
lighten install
|
|
75
|
+
lighten status # should say "Hook self-test: OK"
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Then restart Claude Code (or start a new session).
|
|
79
|
+
|
|
80
|
+
`lighten install` edits `~/.claude/settings.json`. It makes a backup
|
|
81
|
+
first, keeps all your existing settings and hooks, and can be run twice
|
|
82
|
+
safely. If you already set `autoCompactWindow`, Lighten leaves it alone.
|
|
83
|
+
It also adds a small Claude Code plugin (with Claude Code's own
|
|
84
|
+
`claude plugin` commands) that shows Lighten's status line and
|
|
85
|
+
compaction messages. If the plugin can't be added, Lighten uses a
|
|
86
|
+
terminal-only status line instead, and never replaces one you set.
|
|
87
|
+
|
|
88
|
+
Update with `uv tool upgrade lighten`.
|
|
89
|
+
|
|
90
|
+
## See what it saves
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
lighten audit
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
It shows a short summary of what Lighten changed for you, before vs
|
|
97
|
+
with Lighten:
|
|
98
|
+
|
|
99
|
+
- how big the conversation Claude re-reads each reply is
|
|
100
|
+
- **tokens per message**
|
|
101
|
+
- **plan usage per message** (tokens weighted by model price, so cached
|
|
102
|
+
re-reads count least; before = 100)
|
|
103
|
+
- roughly how much more work your 5-hour and weekly limits now fit
|
|
104
|
+
|
|
105
|
+
Each reply counts as "with Lighten" only if Lighten was running in that
|
|
106
|
+
session at the time, so a session you resumed after installing is split
|
|
107
|
+
correctly. `lighten audit --details` shows the full report: cost
|
|
108
|
+
estimates, time per message, session length, compactions, shortened
|
|
109
|
+
outputs, memory notes and the plan-limit history.
|
|
110
|
+
|
|
111
|
+
It also shows your **plan limit** over time (weekly and 5-hour %, from
|
|
112
|
+
Claude Code's `/usage`). Claude Code keeps no history of these, so Lighten
|
|
113
|
+
saves a snapshot when you install it and every time you run
|
|
114
|
+
`lighten audit`. Reading `/usage` uses none of your plan.
|
|
115
|
+
|
|
116
|
+
Sessions in temporary folders (experiments, scripts) are left out; add
|
|
117
|
+
`--include-temp` to count them. Add `--no-usage` to skip the `/usage`
|
|
118
|
+
snapshot.
|
|
119
|
+
|
|
120
|
+
In our own long-session test, Lighten used about **25% less of the 5-hour
|
|
121
|
+
limit** for the same work (79% fewer tokens), with the same results. Your
|
|
122
|
+
numbers depend on how long your sessions get: short sessions that never
|
|
123
|
+
reach 200k tokens see little change.
|
|
124
|
+
|
|
125
|
+
To share your results (for example with the Lighten team):
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
lighten audit --share lighten-report.json
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
The file contains **numbers only**: no code, file paths, prompts or
|
|
132
|
+
commands. Open it and check before you send it.
|
|
133
|
+
|
|
134
|
+
## Options
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
lighten install --compact-window 300000 # compact later (150,000 – 1,000,000)
|
|
138
|
+
lighten install --no-compact-window # don't touch auto-compaction
|
|
139
|
+
lighten install --force # replace an autoCompactWindow you set
|
|
140
|
+
lighten install --no-statusline # no status line and no plugin
|
|
141
|
+
LIGHTEN_DISABLED=1 claude # run one session without Lighten
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
`~/.lighten/config.json` (every key optional; these are the defaults):
|
|
145
|
+
|
|
146
|
+
```json
|
|
147
|
+
{
|
|
148
|
+
"enabled": true,
|
|
149
|
+
"distill": true,
|
|
150
|
+
"memory": true,
|
|
151
|
+
"notify": true,
|
|
152
|
+
"inject_on_startup": true,
|
|
153
|
+
"startup_max_age_hours": 24,
|
|
154
|
+
"max_inject_chars": 4000,
|
|
155
|
+
"output_retention_days": 7
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
- `distill`: shorten noisy command output
|
|
160
|
+
- `memory`: compaction guidance and memory notes
|
|
161
|
+
- `notify`: show a one-line `Lighten · …` message when Lighten acts
|
|
162
|
+
- `inject_on_startup`: give Claude a note from the previous session when you
|
|
163
|
+
start Claude Code in the same project (only if it was within
|
|
164
|
+
`startup_max_age_hours`)
|
|
165
|
+
|
|
166
|
+
## Uninstall
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
lighten uninstall # removes the hooks, plugin and status line, restores your compaction setting
|
|
170
|
+
lighten uninstall --purge # ...and deletes ~/.lighten
|
|
171
|
+
uv tool uninstall lighten
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## What is stored, and where
|
|
175
|
+
|
|
176
|
+
All in `~/.lighten` (or `$LIGHTEN_HOME`), never uploaded:
|
|
177
|
+
|
|
178
|
+
- `projects/<project>/sessions/*.jsonl`: per-session log (your requests,
|
|
179
|
+
changed file paths, commands, what was shortened)
|
|
180
|
+
- `projects/<project>/summaries/*.md`: the last compaction summary
|
|
181
|
+
- `outputs/`: full copies of shortened outputs, deleted after 7 days
|
|
182
|
+
- `logs/errors.log`: hook errors (hooks never interrupt Claude Code)
|
|
183
|
+
- `usage.jsonl`: your plan-limit snapshots (percentages and times)
|
|
184
|
+
|
|
185
|
+
## Known limits
|
|
186
|
+
|
|
187
|
+
- **Failing commands are not shortened.** Claude Code does not let hooks
|
|
188
|
+
rewrite the output of a command that failed, so failing test output
|
|
189
|
+
reaches Claude in full.
|
|
190
|
+
- **File views are never touched** (`cat`, `sed`, `head`, `git diff`, ...).
|
|
191
|
+
If you mostly read code, the savings come from compaction and memory.
|
|
192
|
+
- **Earlier compaction is a trade-off.** Each compaction costs one summary
|
|
193
|
+
call and can lose detail. The window can't be set below 150,000 tokens:
|
|
194
|
+
sessions already start at ~40k, and a smaller window would compact over
|
|
195
|
+
and over.
|
|
196
|
+
- **Tokens and plan limit are not the same.** Your plan counts re-read
|
|
197
|
+
(cached) tokens as much cheaper than new work, and re-reading is what
|
|
198
|
+
Lighten cuts most. So the token saving is larger than the limit saving.
|
|
199
|
+
- A note from the previous session (up to ~1k tokens) is added when you
|
|
200
|
+
start Claude Code in a project you used in the last 24 hours.
|
|
201
|
+
- Tested on Linux with Claude Code 2.1.319. macOS should work; Windows
|
|
202
|
+
is untested.
|
|
203
|
+
|
|
204
|
+
## Upgrading from "trippy"
|
|
205
|
+
|
|
206
|
+
Lighten was called Trippy in early tests. Install Lighten and run
|
|
207
|
+
`lighten install`; it removes the old Trippy hooks automatically. Then
|
|
208
|
+
`uv tool uninstall trippy`. Old data in `~/.trippy` can be deleted.
|
|
209
|
+
|
|
210
|
+
## License
|
|
211
|
+
|
|
212
|
+
Lighten is **free to install and use**, but it is **not open source**.
|
|
213
|
+
You may not copy, modify, redistribute or resell it. The full terms are in
|
|
214
|
+
the `LICENSE` file included with the package.
|
|
215
|
+
|
|
216
|
+
Questions or problems: email the author (address on the PyPI page).
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
Lighten is an independent project and is not affiliated with or endorsed
|
|
221
|
+
by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.
|
lighten-0.3.2/README.md
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
# Lighten — use fewer tokens in Claude Code
|
|
2
|
+
|
|
3
|
+
Every time Claude replies, it re-reads the whole conversation. Long
|
|
4
|
+
conversations make every reply expensive, and they burn through your
|
|
5
|
+
usage limits. Lighten keeps conversations light without losing the
|
|
6
|
+
thread.
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
uv tool install lighten
|
|
10
|
+
lighten install
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
**What it does**
|
|
14
|
+
|
|
15
|
+
1. **Compacts earlier, and better.** Claude Code's auto-compaction is set
|
|
16
|
+
to start at a 200k-token conversation (instead of near 1M), and Lighten
|
|
17
|
+
tells the summary what to keep: your goal, decisions, changed files,
|
|
18
|
+
unresolved errors and next steps.
|
|
19
|
+
2. **Remembers.** Lighten keeps a small log of what happened (your
|
|
20
|
+
requests, files changed, commands that are still failing). After a
|
|
21
|
+
compaction, after `/clear`, or in a new session in the same project,
|
|
22
|
+
it hands Claude a short note so you can start fresh without losing
|
|
23
|
+
your place.
|
|
24
|
+
3. **Shortens noisy command output.** Passing-test lists, install and
|
|
25
|
+
build progress are removed *before* Claude sees them. Errors,
|
|
26
|
+
warnings and anything unrecognised are always kept. The full output
|
|
27
|
+
is saved on your machine, and Claude is told where.
|
|
28
|
+
4. **Tells you when it acts.** A one-line message appears only when
|
|
29
|
+
something happens (`Lighten · compacted 169k → 13k, memory kept`), and
|
|
30
|
+
Claude Code's status area (terminal and editor panel) shows
|
|
31
|
+
`context 84k / compacts at 167k · 5-hour 32% · 2 compactions today`.
|
|
32
|
+
5. **Shows you the numbers.** `lighten audit` reads your local Claude Code
|
|
33
|
+
history and shows where your usage goes, before and with Lighten.
|
|
34
|
+
|
|
35
|
+
Everything runs on your machine. Nothing is sent anywhere.
|
|
36
|
+
|
|
37
|
+
## Install
|
|
38
|
+
|
|
39
|
+
You need Claude Code 2.1.121 or newer and [uv](https://docs.astral.sh/uv/)
|
|
40
|
+
(or pipx). Python 3.10+ is fetched automatically by uv if needed.
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
uv tool install lighten # or: pipx install lighten
|
|
44
|
+
lighten install
|
|
45
|
+
lighten status # should say "Hook self-test: OK"
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Then restart Claude Code (or start a new session).
|
|
49
|
+
|
|
50
|
+
`lighten install` edits `~/.claude/settings.json`. It makes a backup
|
|
51
|
+
first, keeps all your existing settings and hooks, and can be run twice
|
|
52
|
+
safely. If you already set `autoCompactWindow`, Lighten leaves it alone.
|
|
53
|
+
It also adds a small Claude Code plugin (with Claude Code's own
|
|
54
|
+
`claude plugin` commands) that shows Lighten's status line and
|
|
55
|
+
compaction messages. If the plugin can't be added, Lighten uses a
|
|
56
|
+
terminal-only status line instead, and never replaces one you set.
|
|
57
|
+
|
|
58
|
+
Update with `uv tool upgrade lighten`.
|
|
59
|
+
|
|
60
|
+
## See what it saves
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
lighten audit
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
It shows a short summary of what Lighten changed for you, before vs
|
|
67
|
+
with Lighten:
|
|
68
|
+
|
|
69
|
+
- how big the conversation Claude re-reads each reply is
|
|
70
|
+
- **tokens per message**
|
|
71
|
+
- **plan usage per message** (tokens weighted by model price, so cached
|
|
72
|
+
re-reads count least; before = 100)
|
|
73
|
+
- roughly how much more work your 5-hour and weekly limits now fit
|
|
74
|
+
|
|
75
|
+
Each reply counts as "with Lighten" only if Lighten was running in that
|
|
76
|
+
session at the time, so a session you resumed after installing is split
|
|
77
|
+
correctly. `lighten audit --details` shows the full report: cost
|
|
78
|
+
estimates, time per message, session length, compactions, shortened
|
|
79
|
+
outputs, memory notes and the plan-limit history.
|
|
80
|
+
|
|
81
|
+
It also shows your **plan limit** over time (weekly and 5-hour %, from
|
|
82
|
+
Claude Code's `/usage`). Claude Code keeps no history of these, so Lighten
|
|
83
|
+
saves a snapshot when you install it and every time you run
|
|
84
|
+
`lighten audit`. Reading `/usage` uses none of your plan.
|
|
85
|
+
|
|
86
|
+
Sessions in temporary folders (experiments, scripts) are left out; add
|
|
87
|
+
`--include-temp` to count them. Add `--no-usage` to skip the `/usage`
|
|
88
|
+
snapshot.
|
|
89
|
+
|
|
90
|
+
In our own long-session test, Lighten used about **25% less of the 5-hour
|
|
91
|
+
limit** for the same work (79% fewer tokens), with the same results. Your
|
|
92
|
+
numbers depend on how long your sessions get: short sessions that never
|
|
93
|
+
reach 200k tokens see little change.
|
|
94
|
+
|
|
95
|
+
To share your results (for example with the Lighten team):
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
lighten audit --share lighten-report.json
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The file contains **numbers only**: no code, file paths, prompts or
|
|
102
|
+
commands. Open it and check before you send it.
|
|
103
|
+
|
|
104
|
+
## Options
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
lighten install --compact-window 300000 # compact later (150,000 – 1,000,000)
|
|
108
|
+
lighten install --no-compact-window # don't touch auto-compaction
|
|
109
|
+
lighten install --force # replace an autoCompactWindow you set
|
|
110
|
+
lighten install --no-statusline # no status line and no plugin
|
|
111
|
+
LIGHTEN_DISABLED=1 claude # run one session without Lighten
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
`~/.lighten/config.json` (every key optional; these are the defaults):
|
|
115
|
+
|
|
116
|
+
```json
|
|
117
|
+
{
|
|
118
|
+
"enabled": true,
|
|
119
|
+
"distill": true,
|
|
120
|
+
"memory": true,
|
|
121
|
+
"notify": true,
|
|
122
|
+
"inject_on_startup": true,
|
|
123
|
+
"startup_max_age_hours": 24,
|
|
124
|
+
"max_inject_chars": 4000,
|
|
125
|
+
"output_retention_days": 7
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
- `distill`: shorten noisy command output
|
|
130
|
+
- `memory`: compaction guidance and memory notes
|
|
131
|
+
- `notify`: show a one-line `Lighten · …` message when Lighten acts
|
|
132
|
+
- `inject_on_startup`: give Claude a note from the previous session when you
|
|
133
|
+
start Claude Code in the same project (only if it was within
|
|
134
|
+
`startup_max_age_hours`)
|
|
135
|
+
|
|
136
|
+
## Uninstall
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
lighten uninstall # removes the hooks, plugin and status line, restores your compaction setting
|
|
140
|
+
lighten uninstall --purge # ...and deletes ~/.lighten
|
|
141
|
+
uv tool uninstall lighten
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## What is stored, and where
|
|
145
|
+
|
|
146
|
+
All in `~/.lighten` (or `$LIGHTEN_HOME`), never uploaded:
|
|
147
|
+
|
|
148
|
+
- `projects/<project>/sessions/*.jsonl`: per-session log (your requests,
|
|
149
|
+
changed file paths, commands, what was shortened)
|
|
150
|
+
- `projects/<project>/summaries/*.md`: the last compaction summary
|
|
151
|
+
- `outputs/`: full copies of shortened outputs, deleted after 7 days
|
|
152
|
+
- `logs/errors.log`: hook errors (hooks never interrupt Claude Code)
|
|
153
|
+
- `usage.jsonl`: your plan-limit snapshots (percentages and times)
|
|
154
|
+
|
|
155
|
+
## Known limits
|
|
156
|
+
|
|
157
|
+
- **Failing commands are not shortened.** Claude Code does not let hooks
|
|
158
|
+
rewrite the output of a command that failed, so failing test output
|
|
159
|
+
reaches Claude in full.
|
|
160
|
+
- **File views are never touched** (`cat`, `sed`, `head`, `git diff`, ...).
|
|
161
|
+
If you mostly read code, the savings come from compaction and memory.
|
|
162
|
+
- **Earlier compaction is a trade-off.** Each compaction costs one summary
|
|
163
|
+
call and can lose detail. The window can't be set below 150,000 tokens:
|
|
164
|
+
sessions already start at ~40k, and a smaller window would compact over
|
|
165
|
+
and over.
|
|
166
|
+
- **Tokens and plan limit are not the same.** Your plan counts re-read
|
|
167
|
+
(cached) tokens as much cheaper than new work, and re-reading is what
|
|
168
|
+
Lighten cuts most. So the token saving is larger than the limit saving.
|
|
169
|
+
- A note from the previous session (up to ~1k tokens) is added when you
|
|
170
|
+
start Claude Code in a project you used in the last 24 hours.
|
|
171
|
+
- Tested on Linux with Claude Code 2.1.319. macOS should work; Windows
|
|
172
|
+
is untested.
|
|
173
|
+
|
|
174
|
+
## Upgrading from "trippy"
|
|
175
|
+
|
|
176
|
+
Lighten was called Trippy in early tests. Install Lighten and run
|
|
177
|
+
`lighten install`; it removes the old Trippy hooks automatically. Then
|
|
178
|
+
`uv tool uninstall trippy`. Old data in `~/.trippy` can be deleted.
|
|
179
|
+
|
|
180
|
+
## License
|
|
181
|
+
|
|
182
|
+
Lighten is **free to install and use**, but it is **not open source**.
|
|
183
|
+
You may not copy, modify, redistribute or resell it. The full terms are in
|
|
184
|
+
the `LICENSE` file included with the package.
|
|
185
|
+
|
|
186
|
+
Questions or problems: email the author (address on the PyPI page).
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
Lighten is an independent project and is not affiliated with or endorsed
|
|
191
|
+
by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "lighten"
|
|
3
|
+
version = "0.3.2"
|
|
4
|
+
description = "Keep Claude Code conversations light: earlier guided compaction, memory across sessions, and shorter tool output, so you use fewer tokens."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "LicenseRef-Proprietary"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
requires-python = ">=3.10"
|
|
9
|
+
dependencies = []
|
|
10
|
+
keywords = [
|
|
11
|
+
"claude-code",
|
|
12
|
+
"claude",
|
|
13
|
+
"tokens",
|
|
14
|
+
"context",
|
|
15
|
+
"compaction",
|
|
16
|
+
"hooks",
|
|
17
|
+
"llm",
|
|
18
|
+
"cost",
|
|
19
|
+
]
|
|
20
|
+
classifiers = [
|
|
21
|
+
"Development Status :: 3 - Alpha",
|
|
22
|
+
"Environment :: Console",
|
|
23
|
+
"Intended Audience :: Developers",
|
|
24
|
+
"Operating System :: POSIX :: Linux",
|
|
25
|
+
"Operating System :: MacOS",
|
|
26
|
+
"Programming Language :: Python :: 3",
|
|
27
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
28
|
+
"Programming Language :: Python :: 3.10",
|
|
29
|
+
"Programming Language :: Python :: 3.11",
|
|
30
|
+
"Programming Language :: Python :: 3.12",
|
|
31
|
+
"Programming Language :: Python :: 3.13",
|
|
32
|
+
"Programming Language :: Python :: 3.14",
|
|
33
|
+
"Topic :: Software Development",
|
|
34
|
+
"Topic :: Utilities",
|
|
35
|
+
]
|
|
36
|
+
|
|
37
|
+
[[project.authors]]
|
|
38
|
+
name = "sukumarlightningleap"
|
|
39
|
+
email = "sukumar@lightningleap.org"
|
|
40
|
+
|
|
41
|
+
[project.optional-dependencies]
|
|
42
|
+
server = [
|
|
43
|
+
"fastapi>=0.115,<1",
|
|
44
|
+
"pydantic>=2.10,<3",
|
|
45
|
+
"uvicorn[standard]>=0.34,<1",
|
|
46
|
+
]
|
|
47
|
+
|
|
48
|
+
[project.scripts]
|
|
49
|
+
lighten = "lighten.cli.main:main"
|
|
50
|
+
|
|
51
|
+
[dependency-groups]
|
|
52
|
+
dev = [
|
|
53
|
+
"pytest>=8",
|
|
54
|
+
"fastapi>=0.115,<1",
|
|
55
|
+
"httpx2>=2.12.0",
|
|
56
|
+
"pydantic>=2.10,<3",
|
|
57
|
+
"uvicorn[standard]>=0.34,<1",
|
|
58
|
+
]
|
|
59
|
+
|
|
60
|
+
[build-system]
|
|
61
|
+
requires = ["uv_build>=0.11.3,<0.13.0"]
|
|
62
|
+
build-backend = "uv_build"
|
|
63
|
+
|
|
64
|
+
[tool.uv.build-backend]
|
|
65
|
+
module-name = "lighten"
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "lighten"
|
|
3
|
+
version = "0.3.2"
|
|
4
|
+
description = "Keep Claude Code conversations light: earlier guided compaction, memory across sessions, and shorter tool output, so you use fewer tokens."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
# Closed source for now: free to install and use, see LICENSE.
|
|
7
|
+
license = "LicenseRef-Proprietary"
|
|
8
|
+
license-files = ["LICENSE"]
|
|
9
|
+
authors = [
|
|
10
|
+
{ name = "sukumarlightningleap", email = "sukumar@lightningleap.org" }
|
|
11
|
+
]
|
|
12
|
+
requires-python = ">=3.10"
|
|
13
|
+
# The hook runs on every tool call, so the core has no dependencies.
|
|
14
|
+
dependencies = []
|
|
15
|
+
keywords = ["claude-code", "claude", "tokens", "context", "compaction", "hooks", "llm", "cost"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 3 - Alpha",
|
|
18
|
+
"Environment :: Console",
|
|
19
|
+
"Intended Audience :: Developers",
|
|
20
|
+
"Operating System :: POSIX :: Linux",
|
|
21
|
+
"Operating System :: MacOS",
|
|
22
|
+
"Programming Language :: Python :: 3",
|
|
23
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
24
|
+
"Programming Language :: Python :: 3.10",
|
|
25
|
+
"Programming Language :: Python :: 3.11",
|
|
26
|
+
"Programming Language :: Python :: 3.12",
|
|
27
|
+
"Programming Language :: Python :: 3.13",
|
|
28
|
+
"Programming Language :: Python :: 3.14",
|
|
29
|
+
"Topic :: Software Development",
|
|
30
|
+
"Topic :: Utilities",
|
|
31
|
+
]
|
|
32
|
+
|
|
33
|
+
# No [project.urls]: the source repository is meant to be private, and a
|
|
34
|
+
# published release keeps its links forever. Add a website URL here later.
|
|
35
|
+
|
|
36
|
+
[project.optional-dependencies]
|
|
37
|
+
# Legacy HTTP policy service (lighten.api). Not needed by the CLI or hooks.
|
|
38
|
+
server = [
|
|
39
|
+
"fastapi>=0.115,<1",
|
|
40
|
+
"pydantic>=2.10,<3",
|
|
41
|
+
"uvicorn[standard]>=0.34,<1",
|
|
42
|
+
]
|
|
43
|
+
|
|
44
|
+
[project.scripts]
|
|
45
|
+
lighten = "lighten.cli.main:main"
|
|
46
|
+
|
|
47
|
+
[dependency-groups]
|
|
48
|
+
dev = [
|
|
49
|
+
"pytest>=8",
|
|
50
|
+
"fastapi>=0.115,<1",
|
|
51
|
+
"httpx2>=2.12.0",
|
|
52
|
+
"pydantic>=2.10,<3",
|
|
53
|
+
"uvicorn[standard]>=0.34,<1",
|
|
54
|
+
]
|
|
55
|
+
|
|
56
|
+
[build-system]
|
|
57
|
+
requires = ["uv_build>=0.11.3,<0.13.0"]
|
|
58
|
+
build-backend = "uv_build"
|
|
59
|
+
|
|
60
|
+
[tool.uv.build-backend]
|
|
61
|
+
module-name = "lighten"
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.3.2"
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
from fastapi import FastAPI
|
|
2
|
+
|
|
3
|
+
from .routes import router
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
app = FastAPI(
|
|
7
|
+
title="Trippy V2 API",
|
|
8
|
+
version="0.1.0",
|
|
9
|
+
)
|
|
10
|
+
|
|
11
|
+
app.include_router(router)
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
@app.get("/health")
|
|
15
|
+
def health() -> dict[str, str]:
|
|
16
|
+
return {
|
|
17
|
+
"status": "ok",
|
|
18
|
+
"service": "trippy-v2",
|
|
19
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
from fastapi import APIRouter
|
|
2
|
+
|
|
3
|
+
from .schemas import (
|
|
4
|
+
PostToolUseEvent,
|
|
5
|
+
PostToolUseHookResponse,
|
|
6
|
+
)
|
|
7
|
+
|
|
8
|
+
from lighten.integration.request_adapter import (
|
|
9
|
+
adapt_post_tool_use,
|
|
10
|
+
)
|
|
11
|
+
|
|
12
|
+
from lighten.pipeline.curator import (
|
|
13
|
+
TrippyCurator,
|
|
14
|
+
)
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
router = APIRouter()
|
|
18
|
+
|
|
19
|
+
curator = TrippyCurator()
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
@router.post(
|
|
23
|
+
"/hooks/claude/post-tool-use",
|
|
24
|
+
response_model=PostToolUseHookResponse,
|
|
25
|
+
response_model_exclude_none=True,
|
|
26
|
+
)
|
|
27
|
+
def post_tool_use(
|
|
28
|
+
event: PostToolUseEvent,
|
|
29
|
+
) -> dict:
|
|
30
|
+
|
|
31
|
+
request = adapt_post_tool_use(event)
|
|
32
|
+
|
|
33
|
+
result = curator.curate(request)
|
|
34
|
+
|
|
35
|
+
return result.to_hook_response()
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from typing import Any
|
|
4
|
+
|
|
5
|
+
from pydantic import BaseModel, ConfigDict
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class PostToolUseEvent(BaseModel):
|
|
9
|
+
"""
|
|
10
|
+
Claude Code PostToolUse event.
|
|
11
|
+
|
|
12
|
+
extra='allow' is intentional because Claude Code can add
|
|
13
|
+
fields without Trippy needing to reject the request.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
model_config = ConfigDict(extra="allow")
|
|
17
|
+
|
|
18
|
+
session_id: str | None = None
|
|
19
|
+
transcript_path: str | None = None
|
|
20
|
+
cwd: str | None = None
|
|
21
|
+
permission_mode: str | None = None
|
|
22
|
+
|
|
23
|
+
hook_event_name: str = "PostToolUse"
|
|
24
|
+
|
|
25
|
+
tool_name: str
|
|
26
|
+
tool_input: Any = None
|
|
27
|
+
tool_response: Any = None
|
|
28
|
+
|
|
29
|
+
tool_use_id: str | None = None
|
|
30
|
+
duration_ms: float | None = None
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class HookSpecificOutput(BaseModel):
|
|
34
|
+
hookEventName: str = "PostToolUse"
|
|
35
|
+
|
|
36
|
+
updatedToolOutput: Any | None = None
|
|
37
|
+
additionalContext: str | None = None
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class PostToolUseHookResponse(BaseModel):
|
|
41
|
+
hookSpecificOutput: HookSpecificOutput
|
|
File without changes
|