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.
Files changed (61) hide show
  1. lighten-0.3.2/LICENSE +35 -0
  2. lighten-0.3.2/PKG-INFO +221 -0
  3. lighten-0.3.2/README.md +191 -0
  4. lighten-0.3.2/pyproject.toml +65 -0
  5. lighten-0.3.2/pyproject.toml.orig +61 -0
  6. lighten-0.3.2/src/lighten/__init__.py +1 -0
  7. lighten-0.3.2/src/lighten/api/app.py +19 -0
  8. lighten-0.3.2/src/lighten/api/routes.py +35 -0
  9. lighten-0.3.2/src/lighten/api/schemas.py +41 -0
  10. lighten-0.3.2/src/lighten/audit/__init__.py +0 -0
  11. lighten-0.3.2/src/lighten/audit/pricing.py +111 -0
  12. lighten-0.3.2/src/lighten/audit/report.py +1235 -0
  13. lighten-0.3.2/src/lighten/audit/usage.py +193 -0
  14. lighten-0.3.2/src/lighten/auth/api_key.py +30 -0
  15. lighten-0.3.2/src/lighten/claude_plugin/.claude-plugin/marketplace.json +1 -0
  16. lighten-0.3.2/src/lighten/claude_plugin/.claude-plugin/plugin.json +1 -0
  17. lighten-0.3.2/src/lighten/claude_plugin/README.md +7 -0
  18. lighten-0.3.2/src/lighten/claude_plugin/hooks/hooks.json +1 -0
  19. lighten-0.3.2/src/lighten/claude_plugin/hooks/register.ts +129 -0
  20. lighten-0.3.2/src/lighten/clearing/__init__.py +0 -0
  21. lighten-0.3.2/src/lighten/clearing/distillers.py +491 -0
  22. lighten-0.3.2/src/lighten/clearing/engine.py +21 -0
  23. lighten-0.3.2/src/lighten/clearing/history.py +65 -0
  24. lighten-0.3.2/src/lighten/clearing/legacy_detector.py +545 -0
  25. lighten-0.3.2/src/lighten/clearing/renderer.py +195 -0
  26. lighten-0.3.2/src/lighten/clearing/thinking.py +250 -0
  27. lighten-0.3.2/src/lighten/cli/__init__.py +0 -0
  28. lighten-0.3.2/src/lighten/cli/main.py +537 -0
  29. lighten-0.3.2/src/lighten/detection/__init__.py +7 -0
  30. lighten-0.3.2/src/lighten/detection/tool_detector.py +42 -0
  31. lighten-0.3.2/src/lighten/hooks/__init__.py +0 -0
  32. lighten-0.3.2/src/lighten/hooks/__main__.py +84 -0
  33. lighten-0.3.2/src/lighten/hooks/dispatch.py +661 -0
  34. lighten-0.3.2/src/lighten/install/__init__.py +0 -0
  35. lighten-0.3.2/src/lighten/install/plugin.py +93 -0
  36. lighten-0.3.2/src/lighten/install/settings.py +462 -0
  37. lighten-0.3.2/src/lighten/integration/__init__.py +0 -0
  38. lighten-0.3.2/src/lighten/integration/claude_code.py +41 -0
  39. lighten-0.3.2/src/lighten/integration/request_adapter.py +51 -0
  40. lighten-0.3.2/src/lighten/integration/response_builder.py +37 -0
  41. lighten-0.3.2/src/lighten/memory/__init__.py +0 -0
  42. lighten-0.3.2/src/lighten/memory/handoff.py +319 -0
  43. lighten-0.3.2/src/lighten/memory/store.py +416 -0
  44. lighten-0.3.2/src/lighten/models/__init__.py +22 -0
  45. lighten-0.3.2/src/lighten/models/context.py +10 -0
  46. lighten-0.3.2/src/lighten/models/decision.py +27 -0
  47. lighten-0.3.2/src/lighten/models/tokenization.py +49 -0
  48. lighten-0.3.2/src/lighten/models/tool_result.py +109 -0
  49. lighten-0.3.2/src/lighten/pipeline/__init__.py +0 -0
  50. lighten-0.3.2/src/lighten/pipeline/curator.py +89 -0
  51. lighten-0.3.2/src/lighten/policy/__init__.py +0 -0
  52. lighten-0.3.2/src/lighten/policy/clearing_policy.py +257 -0
  53. lighten-0.3.2/src/lighten/policy/threshold.py +11 -0
  54. lighten-0.3.2/src/lighten/profiling/__init__.py +5 -0
  55. lighten-0.3.2/src/lighten/profiling/fidelity.py +27 -0
  56. lighten-0.3.2/src/lighten/profiling/refetchability.py +42 -0
  57. lighten-0.3.2/src/lighten/profiling/repetition.py +37 -0
  58. lighten-0.3.2/src/lighten/profiling/size.py +14 -0
  59. lighten-0.3.2/src/lighten/profiling/structure.py +29 -0
  60. lighten-0.3.2/src/lighten/profiling/tool_profiler.py +322 -0
  61. 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.
@@ -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