PyPI - kompactor - Versions diffs - 0.7.3__tar.gz → 0.7.4__tar.gz - Mend

kompactor 0.7.3tar.gz → 0.7.4tar.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 (42) hide show

{kompactor-0.7.3 → kompactor-0.7.4}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kompactor
-Version: 0.7.3
+Version: 0.7.4
 Summary: Cut the tokens Claude Code spends on noise: compacted command output (failing runs included), outline-first reads, a local code graph, and per-turn savings.
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/amarkum/kompactor
@@ -21,7 +21,10 @@ Requires-Dist: tiktoken>=0.7; extra == "exact"
 Dynamic: license-file
 <p align="center">
-  <img src="https://raw.githubusercontent.com/amarkum/kompactor/main/docs/brand/kompactor-logo-light.png" alt="Kompactor" width="240">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/amarkum/kompactor/main/docs/brand/kompactor-logo-dark.png">
+    <img src="https://raw.githubusercontent.com/amarkum/kompactor/main/docs/brand/kompactor-logo-light.png" alt="Kompactor" width="240">
+  </picture>
 </p>
 <p align="center"><b>Cut the tokens Claude Code spends on noise.</b><br>
@@ -39,7 +42,7 @@ Most of a Claude Code session's tokens aren't your prompt or Claude's answer. Th
 ## Contents
-[Install](#install) · [After you install](#after-you-install) · [How it works](#how-it-works) · [Use it from Claude Code](#use-it-from-claude-code) · [Quality vs tokens](#quality-vs-tokens) · [See your savings](#see-your-savings) · [Turn it off](#turn-it-off-or-remove-it) · [Evidence](#evidence) · [Code graph](#code-graph) · [Teams](#use-it-across-a-team) · [Commands](#commands)
+[Install](#install) · [After you install](#after-you-install) · [How it works](#how-it-works) · [Examples](#examples) · [Use it from Claude Code](#use-it-from-claude-code) · [Quality vs tokens](#quality-vs-tokens) · [See your savings](#see-your-savings) · [Turn it off](#turn-it-off-or-remove-it) · [What it runs and changes](#what-kompactor-runs-and-changes) · [Evidence](#evidence) · [Code graph](#code-graph) · [Teams](#use-it-across-a-team) · [Troubleshooting](#troubleshooting) · [Commands](#commands) · [Support](#support-and-security)
 ## Install
@@ -59,7 +62,7 @@ pipx install kompactor        # or: pip install kompactor · uv tool install kom
 kompactor setup
 ```
-**VS Code.** Download `kompactor-0.7.3.vsix` from [Releases](https://github.com/amarkum/kompactor/releases), install it (Extensions › `⋯` › *Install from VSIX…*), and click **Enable** when Kompactor asks.
+**VS Code.** Download `kompactor-0.7.4.vsix` from [Releases](https://github.com/amarkum/kompactor/releases), install it (Extensions › `⋯` › *Install from VSIX…*), and click **Enable** when Kompactor asks.
 ## After you install
@@ -67,7 +70,7 @@ kompactor setup
 2. **Work as usual.** You don't call Kompactor; it acts on Claude's tool calls by itself. After each reply you'll see a line such as `Kompactor: −8.2k tokens this turn`, and the status line shows the running total.
 3. **Check it's on:** run `kompactor` in a terminal (or `/kompactor` in Claude Code). It shows whether it's on, your level, savings so far and how to change things:
    ```
-   Kompactor 0.7.3: ON
+   Kompactor 0.7.4: ON
      Connected via the Claude Code plugin. New Claude Code sessions are compacted.
      Level: Balanced (level 3 of 5). Change it: `kompactor config preset 1-5`, the dashboard, or /kompactor balanced
      Saved so far: 41.3k tokens (−38%) over 52 tool calls. Details: `kompactor gain`
@@ -88,6 +91,18 @@ Kompactor uses Claude Code's hooks, so it sits between Claude's tools and Claude
 **Nothing is lost.** Every shortened output keeps a raw copy that Claude can fetch with `kompactor show <id>`. Kompactor never changes what a command does, your permission rules still apply, and if anything goes wrong it lets the original output through. Everything runs on your machine; nothing is sent anywhere ([privacy](https://github.com/amarkum/kompactor/blob/main/PRIVACY.md)).
+## Examples
+Ask Claude Code the way you normally would. These prompts come from the [evidence](#evidence) runs:
+| You ask | What Kompactor does | Measured |
+|---|---|---|
+| "Run the tests and tell me which one fails and why." | Claude sees the failing test, its error and the summary line instead of hundreds of passing tests, even when the run exits non-zero. | Go: −33% tokens; vitest: −37% cost |
+| "Where is the session cookie signed?" | Big files arrive as outlines with line ranges, and the first search adds a short map of the main modules, so Claude finds the code in fewer turns. | Flask: −26% tokens |
+| "Install the dependencies and check that it builds." | Download and progress chatter is dropped; warnings, errors and the result are kept. | `npm install`: ~33,000 › 469 tokens |
+| "What does changing `createStore` affect?" | The code graph lists the files that use it and the tests to run. | 27/27 answers correct |
+| `/kompactor review` | Lists cuts in your current diff: duplicated helpers, unused options, dead branches. | |
 ## Use it from Claude Code
 Type these in any Claude Code chat:
@@ -140,6 +155,20 @@ kompactor uninstall   # remove hooks, status line, shell prefix and skill (add -
 ```
 Then remove the package the way you installed it: `claude plugin uninstall kompactor`, `pipx uninstall kompactor`, or uninstall the extension in VS Code. Setup never replaces a status line or shell prefix you already had, and keeps a backup in `~/.claude/settings.json.kompactor-backup`.
+## What Kompactor runs and changes
+Everything below happens on your machine. Kompactor makes no network requests of its own and has no telemetry. (If you install the optional `tiktoken` package for exact token counts, tiktoken downloads its token table once, on first use.)
+**What it runs.** Python hooks that Claude Code calls (`python3 kompactor/_launch.py hook <name>` from the plugin folder): after Bash, Read, Grep, Glob and edit tool calls; before Read; at session start, subagent start and before compaction; and when a turn ends. After `/kompactor setup` on macOS and Linux, Claude's Bash commands run through Kompactor's shell prefix (`~/.kompactor/bin/kompactor-shell`) so failing runs can be compacted too. The prefix runs after Claude Code's permission check, on Claude's original command, and returns its exit code unchanged.
+**What it adds to Claude's context.** Compacted tool output, outlines in place of large file reads, a code map once per session, a one-line savings note after each turn, and short reply rules at session start and for subagents. The rules are plain text you can read in [`kompactor/rules.py`](https://github.com/amarkum/kompactor/blob/main/kompactor/rules.py); the level decides which ones apply (none at level 1).
+**What it reads.** The tool output Claude Code passes to its hooks, the files Claude reads (to outline them), your project's source (for the code graph), and the context size Claude Code gives the status line. Hooks never read your session transcripts. `kompactor estimate` and the dashboard's **Replay your history** panel read your local Claude Code session logs in `~/.claude/projects`, only when you run them, to show what Kompactor would have saved; the result isn't stored or sent anywhere.
+**What it writes.** `~/.kompactor/`: settings, the savings ledger, raw copies of shortened output (for `kompactor show`), the code graph index and the `~/.kompactor/bin/` launchers (written at session start). History is deleted after 30 days by default (`retention_days`). Setup edits `~/.claude/settings.json` to add Kompactor's hooks (non-plugin installs), a status line (only if you have none) and `CLAUDE_CODE_SHELL_PREFIX` (only if it isn't set), keeping a backup in `settings.json.kompactor-backup`; non-plugin installs also get the `/kompactor` skill in `~/.claude/skills`. Nothing is written to your repositories.
+**What it never does.** Change your permission rules or sandbox settings, change what a command does, or send your code or output anywhere. Details: [privacy policy](https://github.com/amarkum/kompactor/blob/main/PRIVACY.md).
 ## Evidence
 `kompactor prove` runs each task in real headless Claude Code sessions (`claude -p`), 3 times without Kompactor and 3 times with it, interleaved, with the same prompt, tools, turn limit and budget cap. Tokens are input + cache writes + cache reads + output across every API call; cost is Claude Code's own figure.
@@ -218,7 +247,17 @@ When a teammate trusts the folder, Claude Code installs the plugin; each person
 { "preset": 4, "overrides": { "never_compact": ["terraform plan"] } }
 ```
-**Admins** can put the same keys in Claude Code's managed settings to roll it out to every machine. To control what your team runs, fork the repo and use `your-org/kompactor` in the commands above. The [usage guide](https://github.com/amarkum/kompactor/blob/main/docs/usage.html) (also in the dashboard as **Guide**) covers rollout, troubleshooting and FAQs.
+**Admins** can put the same keys in Claude Code's managed settings to roll it out to every machine. To control what your team runs, fork the repo and use `your-org/kompactor` in the commands above. The dashboard's **Guide** page covers rollout, settings and FAQs in more detail.
+## Troubleshooting
+| Problem | What to do |
+|---|---|
+| No savings line after replies | Restart Claude Code after setup, then run `kompactor doctor`: it checks the installation and shows recent hook errors. The dashboard's **Self-test** panel runs every hook once. |
+| An output looks too short | Claude can fetch the original with `kompactor show <id>` (the id is in the shortened output), or search earlier outputs with `kompactor search "text"`. |
+| A command should never be shortened | Add it to **Never compact these commands** on the dashboard, or in `.kompactor.json` (`"never_compact": ["terraform plan"]`). For a single run, start the command with `KOMPACTOR_RAW=1`. |
+| Something seems off | `kompactor stop` turns Kompactor off at once; every hook also lets the original output through if it hits an error. Errors are logged to `~/.kompactor/hook-errors.log`. |
+| The dashboard port is busy | `kompactor start` picks a free port by itself and prints the address. |
 ## Commands
@@ -239,7 +278,7 @@ kompactor ui                      the dashboard, in the foreground
 ## Development
 ```bash
-python -m unittest discover tests     # 81 tests, including the real shell prefix run as Claude Code runs it
+python -m unittest discover tests     # 80 tests, including the real shell prefix run as Claude Code runs it
 node vscode/test/smoke.js             # VS Code extension against a mock API
 ./scripts/build-vsix.sh               # › dist/kompactor-<version>.vsix
 python scripts/bump_version.py X.Y.Z  # bump every version; pushing to main publishes to PyPI
@@ -249,4 +288,10 @@ How Claude Code's hooks behave on success, failure and very long output, and why
 Kompactor was called Kompact until version 0.4; installing it replaces an old Kompact install's settings.
-[Privacy](https://github.com/amarkum/kompactor/blob/main/PRIVACY.md) · [MIT License](https://github.com/amarkum/kompactor/blob/main/LICENSE)
+## Support and security
+- **Questions, bugs and ideas:** [open an issue](https://github.com/amarkum/kompactor/issues).
+- **Security problems:** please report them privately, as described in [SECURITY.md](https://github.com/amarkum/kompactor/blob/main/SECURITY.md).
+- **Privacy:** [PRIVACY.md](https://github.com/amarkum/kompactor/blob/main/PRIVACY.md) explains what Kompactor stores and how to delete it.
+[MIT License](https://github.com/amarkum/kompactor/blob/main/LICENSE)

{kompactor-0.7.3 → kompactor-0.7.4}/README.md RENAMED Viewed

@@ -1,5 +1,8 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/amarkum/kompactor/main/docs/brand/kompactor-logo-light.png" alt="Kompactor" width="240">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/amarkum/kompactor/main/docs/brand/kompactor-logo-dark.png">
+    <img src="https://raw.githubusercontent.com/amarkum/kompactor/main/docs/brand/kompactor-logo-light.png" alt="Kompactor" width="240">
+  </picture>
 </p>
 <p align="center"><b>Cut the tokens Claude Code spends on noise.</b><br>
@@ -17,7 +20,7 @@ Most of a Claude Code session's tokens aren't your prompt or Claude's answer. Th
 ## Contents
-[Install](#install) · [After you install](#after-you-install) · [How it works](#how-it-works) · [Use it from Claude Code](#use-it-from-claude-code) · [Quality vs tokens](#quality-vs-tokens) · [See your savings](#see-your-savings) · [Turn it off](#turn-it-off-or-remove-it) · [Evidence](#evidence) · [Code graph](#code-graph) · [Teams](#use-it-across-a-team) · [Commands](#commands)
+[Install](#install) · [After you install](#after-you-install) · [How it works](#how-it-works) · [Examples](#examples) · [Use it from Claude Code](#use-it-from-claude-code) · [Quality vs tokens](#quality-vs-tokens) · [See your savings](#see-your-savings) · [Turn it off](#turn-it-off-or-remove-it) · [What it runs and changes](#what-kompactor-runs-and-changes) · [Evidence](#evidence) · [Code graph](#code-graph) · [Teams](#use-it-across-a-team) · [Troubleshooting](#troubleshooting) · [Commands](#commands) · [Support](#support-and-security)
 ## Install
@@ -37,7 +40,7 @@ pipx install kompactor        # or: pip install kompactor · uv tool install kom
 kompactor setup
 ```
-**VS Code.** Download `kompactor-0.7.3.vsix` from [Releases](https://github.com/amarkum/kompactor/releases), install it (Extensions › `⋯` › *Install from VSIX…*), and click **Enable** when Kompactor asks.
+**VS Code.** Download `kompactor-0.7.4.vsix` from [Releases](https://github.com/amarkum/kompactor/releases), install it (Extensions › `⋯` › *Install from VSIX…*), and click **Enable** when Kompactor asks.
 ## After you install
@@ -45,7 +48,7 @@ kompactor setup
 2. **Work as usual.** You don't call Kompactor; it acts on Claude's tool calls by itself. After each reply you'll see a line such as `Kompactor: −8.2k tokens this turn`, and the status line shows the running total.
 3. **Check it's on:** run `kompactor` in a terminal (or `/kompactor` in Claude Code). It shows whether it's on, your level, savings so far and how to change things:
    ```
-   Kompactor 0.7.3: ON
+   Kompactor 0.7.4: ON
      Connected via the Claude Code plugin. New Claude Code sessions are compacted.
      Level: Balanced (level 3 of 5). Change it: `kompactor config preset 1-5`, the dashboard, or /kompactor balanced
      Saved so far: 41.3k tokens (−38%) over 52 tool calls. Details: `kompactor gain`
@@ -66,6 +69,18 @@ Kompactor uses Claude Code's hooks, so it sits between Claude's tools and Claude
 **Nothing is lost.** Every shortened output keeps a raw copy that Claude can fetch with `kompactor show <id>`. Kompactor never changes what a command does, your permission rules still apply, and if anything goes wrong it lets the original output through. Everything runs on your machine; nothing is sent anywhere ([privacy](https://github.com/amarkum/kompactor/blob/main/PRIVACY.md)).
+## Examples
+Ask Claude Code the way you normally would. These prompts come from the [evidence](#evidence) runs:
+| You ask | What Kompactor does | Measured |
+|---|---|---|
+| "Run the tests and tell me which one fails and why." | Claude sees the failing test, its error and the summary line instead of hundreds of passing tests, even when the run exits non-zero. | Go: −33% tokens; vitest: −37% cost |
+| "Where is the session cookie signed?" | Big files arrive as outlines with line ranges, and the first search adds a short map of the main modules, so Claude finds the code in fewer turns. | Flask: −26% tokens |
+| "Install the dependencies and check that it builds." | Download and progress chatter is dropped; warnings, errors and the result are kept. | `npm install`: ~33,000 › 469 tokens |
+| "What does changing `createStore` affect?" | The code graph lists the files that use it and the tests to run. | 27/27 answers correct |
+| `/kompactor review` | Lists cuts in your current diff: duplicated helpers, unused options, dead branches. | |
 ## Use it from Claude Code
 Type these in any Claude Code chat:
@@ -118,6 +133,20 @@ kompactor uninstall   # remove hooks, status line, shell prefix and skill (add -
 ```
 Then remove the package the way you installed it: `claude plugin uninstall kompactor`, `pipx uninstall kompactor`, or uninstall the extension in VS Code. Setup never replaces a status line or shell prefix you already had, and keeps a backup in `~/.claude/settings.json.kompactor-backup`.
+## What Kompactor runs and changes
+Everything below happens on your machine. Kompactor makes no network requests of its own and has no telemetry. (If you install the optional `tiktoken` package for exact token counts, tiktoken downloads its token table once, on first use.)
+**What it runs.** Python hooks that Claude Code calls (`python3 kompactor/_launch.py hook <name>` from the plugin folder): after Bash, Read, Grep, Glob and edit tool calls; before Read; at session start, subagent start and before compaction; and when a turn ends. After `/kompactor setup` on macOS and Linux, Claude's Bash commands run through Kompactor's shell prefix (`~/.kompactor/bin/kompactor-shell`) so failing runs can be compacted too. The prefix runs after Claude Code's permission check, on Claude's original command, and returns its exit code unchanged.
+**What it adds to Claude's context.** Compacted tool output, outlines in place of large file reads, a code map once per session, a one-line savings note after each turn, and short reply rules at session start and for subagents. The rules are plain text you can read in [`kompactor/rules.py`](https://github.com/amarkum/kompactor/blob/main/kompactor/rules.py); the level decides which ones apply (none at level 1).
+**What it reads.** The tool output Claude Code passes to its hooks, the files Claude reads (to outline them), your project's source (for the code graph), and the context size Claude Code gives the status line. Hooks never read your session transcripts. `kompactor estimate` and the dashboard's **Replay your history** panel read your local Claude Code session logs in `~/.claude/projects`, only when you run them, to show what Kompactor would have saved; the result isn't stored or sent anywhere.
+**What it writes.** `~/.kompactor/`: settings, the savings ledger, raw copies of shortened output (for `kompactor show`), the code graph index and the `~/.kompactor/bin/` launchers (written at session start). History is deleted after 30 days by default (`retention_days`). Setup edits `~/.claude/settings.json` to add Kompactor's hooks (non-plugin installs), a status line (only if you have none) and `CLAUDE_CODE_SHELL_PREFIX` (only if it isn't set), keeping a backup in `settings.json.kompactor-backup`; non-plugin installs also get the `/kompactor` skill in `~/.claude/skills`. Nothing is written to your repositories.
+**What it never does.** Change your permission rules or sandbox settings, change what a command does, or send your code or output anywhere. Details: [privacy policy](https://github.com/amarkum/kompactor/blob/main/PRIVACY.md).
 ## Evidence
 `kompactor prove` runs each task in real headless Claude Code sessions (`claude -p`), 3 times without Kompactor and 3 times with it, interleaved, with the same prompt, tools, turn limit and budget cap. Tokens are input + cache writes + cache reads + output across every API call; cost is Claude Code's own figure.
@@ -196,7 +225,17 @@ When a teammate trusts the folder, Claude Code installs the plugin; each person
 { "preset": 4, "overrides": { "never_compact": ["terraform plan"] } }
 ```
-**Admins** can put the same keys in Claude Code's managed settings to roll it out to every machine. To control what your team runs, fork the repo and use `your-org/kompactor` in the commands above. The [usage guide](https://github.com/amarkum/kompactor/blob/main/docs/usage.html) (also in the dashboard as **Guide**) covers rollout, troubleshooting and FAQs.
+**Admins** can put the same keys in Claude Code's managed settings to roll it out to every machine. To control what your team runs, fork the repo and use `your-org/kompactor` in the commands above. The dashboard's **Guide** page covers rollout, settings and FAQs in more detail.
+## Troubleshooting
+| Problem | What to do |
+|---|---|
+| No savings line after replies | Restart Claude Code after setup, then run `kompactor doctor`: it checks the installation and shows recent hook errors. The dashboard's **Self-test** panel runs every hook once. |
+| An output looks too short | Claude can fetch the original with `kompactor show <id>` (the id is in the shortened output), or search earlier outputs with `kompactor search "text"`. |
+| A command should never be shortened | Add it to **Never compact these commands** on the dashboard, or in `.kompactor.json` (`"never_compact": ["terraform plan"]`). For a single run, start the command with `KOMPACTOR_RAW=1`. |
+| Something seems off | `kompactor stop` turns Kompactor off at once; every hook also lets the original output through if it hits an error. Errors are logged to `~/.kompactor/hook-errors.log`. |
+| The dashboard port is busy | `kompactor start` picks a free port by itself and prints the address. |
 ## Commands
@@ -217,7 +256,7 @@ kompactor ui                      the dashboard, in the foreground
 ## Development
 ```bash
-python -m unittest discover tests     # 81 tests, including the real shell prefix run as Claude Code runs it
+python -m unittest discover tests     # 80 tests, including the real shell prefix run as Claude Code runs it
 node vscode/test/smoke.js             # VS Code extension against a mock API
 ./scripts/build-vsix.sh               # › dist/kompactor-<version>.vsix
 python scripts/bump_version.py X.Y.Z  # bump every version; pushing to main publishes to PyPI
@@ -227,4 +266,10 @@ How Claude Code's hooks behave on success, failure and very long output, and why
 Kompactor was called Kompact until version 0.4; installing it replaces an old Kompact install's settings.
-[Privacy](https://github.com/amarkum/kompactor/blob/main/PRIVACY.md) · [MIT License](https://github.com/amarkum/kompactor/blob/main/LICENSE)
+## Support and security
+- **Questions, bugs and ideas:** [open an issue](https://github.com/amarkum/kompactor/issues).
+- **Security problems:** please report them privately, as described in [SECURITY.md](https://github.com/amarkum/kompactor/blob/main/SECURITY.md).
+- **Privacy:** [PRIVACY.md](https://github.com/amarkum/kompactor/blob/main/PRIVACY.md) explains what Kompactor stores and how to delete it.
+[MIT License](https://github.com/amarkum/kompactor/blob/main/LICENSE)

{kompactor-0.7.3 → kompactor-0.7.4}/kompactor/__init__.py RENAMED Viewed

@@ -1,3 +1,3 @@
 """Kompactor: cut the tokens Claude Code spends on noise."""
-__version__ = "0.7.3"
+__version__ = "0.7.4"

{kompactor-0.7.3 → kompactor-0.7.4}/kompactor/cli.py RENAMED Viewed

@@ -391,7 +391,7 @@ def cmd_uninstall(a):
         print("  Kept savings history and config in ~/.kompactor (add --purge to delete).")
     if installer.status()["plugin_enabled"]:
         print("  The Claude Code plugin is still enabled; run: claude plugin uninstall kompactor")
-    print("  If you installed with pip/pipx/uv, also run: pipx uninstall kompactor")
+    print("  Installed it as a Python package? Remove that too, with the tool you installed it with (pip, pipx or uv).")
     return 0
@@ -411,13 +411,18 @@ def cmd_statusline(a):
         print("Kompactor · stopped (kompactor start)")
         return 0
     sid = event.get("session_id", "")
+    ctx = (event.get("context_window") or {}).get("total_input_tokens")
+    ctx = int(ctx) if isinstance(ctx, (int, float)) and ctx > 0 else 0
+    if sid and ctx:
+        store.note_context(sid, ctx)
     cfg = config.load((event.get("workspace") or {}).get("current_dir") or event.get("cwd") or os.getcwd())
     name = config.PRESETS[cfg["preset"]]["name"]
     tot = store.session_totals(sid) if sid else {}
     if tot.get("saved", 0) > 0:
         parts = [f"Kompactor −{hooks._fmt(tot['saved'])}"]
-        if tot["context"] and tot["in_context_saved"] > 0:
-            parts.append(f"ctx −{100 * tot['in_context_saved'] / (tot['context'] + tot['in_context_saved']):.0f}%")
+        ctx = ctx or tot["context"]
+        if ctx and tot["in_context_saved"] > 0:
+            parts.append(f"ctx −{100 * tot['in_context_saved'] / (ctx + tot['in_context_saved']):.0f}%")
         if tot["last_turn_saved"] > 0:
             parts.append(f"last turn −{hooks._fmt(tot['last_turn_saved'])}")
         parts.append(name)

{kompactor-0.7.3 → kompactor-0.7.4}/kompactor/hooks.py RENAMED Viewed

@@ -284,28 +284,6 @@ def session_start(event: dict, cfg: dict) -> None:
         _emit({"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": text}})
-def _context_tokens(transcript_path: str) -> int:
-    """Size of the context Claude last saw, from the newest usage block in the transcript."""
-    try:
-        with open(transcript_path, "rb") as f:
-            f.seek(0, 2)
-            f.seek(max(0, f.tell() - 400_000))
-            tail = f.read().decode("utf-8", "replace").splitlines()
-    except (OSError, TypeError):
-        return 0
-    for line in reversed(tail):
-        if '"usage"' not in line:
-            continue
-        try:
-            u = json.loads(line).get("message", {}).get("usage", {})
-        except ValueError:
-            continue
-        if u:
-            return int(u.get("input_tokens", 0) + u.get("cache_read_input_tokens", 0)
-                       + u.get("cache_creation_input_tokens", 0))
-    return 0
 def turn_message(turn: dict, totals: dict) -> str:
     parts = []
     if turn["saved"] > 0:
@@ -325,7 +303,7 @@ def stop(event: dict, cfg: dict) -> None:
     if event.get("stop_hook_active"):
         return
     session = event.get("session_id", "")
-    ctx = _context_tokens(event.get("transcript_path", ""))
+    ctx = store.context_size(session)  # recorded by the status line; transcripts are never read
     turn, totals = store.close_turn(session, cfg["project"], ctx)
     msg = turn_message(turn, totals)
     store.write_live({"ts": time.time(), "session": session, "project": cfg["project"], "preset": cfg["preset"],

{kompactor-0.7.3 → kompactor-0.7.4}/kompactor/installer.py RENAMED Viewed

@@ -91,7 +91,7 @@ def prefix_path() -> Path:
 def prefix_active() -> bool:
     """True inside a Claude Code session whose Bash commands run through Kompactor's shell prefix."""
-    cur = os.environ.get(PREFIX_ENV, "")
+    cur = os.environ.get("CLAUDE_CODE_SHELL_PREFIX", "")
     return bool(PREFIX_OURS.search(cur)) and os.path.exists(cur)
@@ -122,10 +122,10 @@ def parse_source(url: str) -> dict:
     return {"repo": repo, "clone": url, "marketplace": url, "dir": parts[-1]}
-def source() -> dict:
+def source(repo=None) -> dict:
     """The repo the dashboard's setup instructions name: Kompactor's public repo, or a team's fork set
     with KOMPACTOR_REPO (owner/repo or a git URL). Nothing is read from git or install records."""
-    url = os.environ.get("KOMPACTOR_REPO", "").strip() or DEFAULT_REPO
+    url = (os.environ.get("KOMPACTOR_REPO", "") if repo is None else repo).strip() or DEFAULT_REPO
     if re.fullmatch(r"[\w.-]+/[\w.-]+", url):
         url = f"https://github.com/{url}"
     return parse_source(url)
@@ -292,6 +292,15 @@ def install(scope: str = "user", project: str = "", statusline: bool = True, uni
 # self-test: run every installed hook command exactly as Claude Code would
+def _selftest_env(tmp: str) -> dict:
+    """Only what a hook needs to start: the self-test never hands hooks the rest of your environment."""
+    env = {"PATH": os.environ.get("PATH", ""), "HOME": os.environ.get("HOME", ""),
+           "USERPROFILE": os.environ.get("USERPROFILE", ""), "SYSTEMROOT": os.environ.get("SYSTEMROOT", ""),
+           "TMPDIR": os.environ.get("TMPDIR", ""), "TEMP": os.environ.get("TEMP", ""),
+           "TMP": os.environ.get("TMP", ""), "LANG": os.environ.get("LANG", "")}
+    return {**{k: v for k, v in env.items() if v}, "KOMPACTOR_HOME": tmp}
 def selftest() -> list:
     """Run each Kompactor hook from settings.json with a realistic event in an isolated
     KOMPACTOR_HOME. Returns [{hook, ok, ms, detail}]."""
@@ -337,7 +346,7 @@ def selftest() -> list:
                 continue
             cmd = f"{launcher()} hook {handler}"  # plugin hooks: exercise the same code path
         ev = {"session_id": "kompactor-selftest", "cwd": tmp, "hook_event_name": event, **events[handler]}
-        env = dict(os.environ, KOMPACTOR_HOME=tmp)
+        env = _selftest_env(tmp)
         t0 = _time.time()
         try:
             p = subprocess.run(cmd, shell=True, input=json.dumps(ev), capture_output=True, text=True, timeout=20,
@@ -372,7 +381,7 @@ def _check_prefix(prefix: str, tmp: str) -> dict:
     t0 = _time.time()
     try:
         p = subprocess.run([prefix, full], capture_output=True, text=True, timeout=30,
-                           env=dict(os.environ, KOMPACTOR_HOME=tmp))
+                           env=_selftest_env(tmp))
         ok = p.returncode == 1 and "test_boom" in p.stdout and "test_7 PASSED" not in p.stdout and "[kompactor:" in p.stdout
         detail = "ok" if ok else f"exit {p.returncode}: {(p.stdout + p.stderr)[-160:]}"
     except (OSError, subprocess.TimeoutExpired) as e:

{kompactor-0.7.3 → kompactor-0.7.4}/kompactor/static/usage.html RENAMED Viewed

@@ -139,7 +139,7 @@ svg.chev { width: 11px; height: 11px; stroke: var(--ink-3); fill: none; stroke-w
           <pre><code>pipx install kompactor
 kompactor setup</code></pre></div>
         <div class="card"><b>VS Code</b><span class="muted">Download the extension file from the repo's Releases page, then click <b>Enable</b> when Kompactor asks.</span>
-          <pre><code>code --install-extension kompactor-0.7.3.vsix</code></pre></div>
+          <pre><code>code --install-extension kompactor-0.7.4.vsix</code></pre></div>
       </div>
       <p class="muted">Windows: run <code>.\kompactor\install.ps1</code> from a clone, or use the VS Code extension. The CLI and the VS Code extension read the same <code>~/.claude/settings.json</code>, so one install covers both. A backup of that file is kept as <code>settings.json.kompactor-backup</code>.</p>
       <p class="muted">Setup adds hooks, a status line (if you don't have one) and, on macOS and Linux, Claude Code's <code>CLAUDE_CODE_SHELL_PREFIX</code> setting pointing at <code>~/.kompactor/bin/kompactor-shell</code>, which is what lets Kompactor compact failing commands. It never replaces a status line or shell prefix you already have. Restart open Claude Code sessions after setup.</p>

{kompactor-0.7.3 → kompactor-0.7.4}/kompactor/store.py RENAMED Viewed

@@ -30,6 +30,9 @@ CREATE TABLE IF NOT EXISTS turns (
     session TEXT, idx INTEGER, ts REAL, project TEXT, raw_tokens INTEGER, kept_tokens INTEGER,
     context_tokens INTEGER, features TEXT
 );
+CREATE TABLE IF NOT EXISTS context (
+    session TEXT PRIMARY KEY, tokens INTEGER, ts REAL
+);
 """
@@ -113,6 +116,19 @@ def close_turn(session: str, project: str, context_tokens: int = 0):
     return turn, totals
+def note_context(session: str, tokens: int) -> None:
+    """The context size Claude Code hands the status line (context_window.total_input_tokens).
+    Kompactor never reads session transcripts for it."""
+    with connect() as db:
+        db.execute("INSERT OR REPLACE INTO context VALUES (?,?,?)", (session, int(tokens), time.time()))
+def context_size(session: str) -> int:
+    with connect() as db:
+        row = db.execute("SELECT tokens FROM context WHERE session=?", (session,)).fetchone()
+    return row[0] if row else 0
 def session_totals(session: str) -> dict:
     """Savings so far for one session (for status lines when several sessions run at once)."""
     with connect() as db:
@@ -138,6 +154,7 @@ def prune(retention_days: float) -> None:
             db.execute(f"DELETE FROM {table} WHERE ts < ?", (cutoff,))
         db.execute("DELETE FROM reads WHERE ts < ?", (time.time() - 2 * 86400,))
         db.execute("DELETE FROM flags WHERE ts < ?", (time.time() - 2 * 86400,))
+        db.execute("DELETE FROM context WHERE ts < ?", (time.time() - 2 * 86400,))
         db.execute("DELETE FROM sessions WHERE COALESCE(NULLIF(last_turn, 0), started) < ?", (cutoff,))

{kompactor-0.7.3 → kompactor-0.7.4}/kompactor.egg-info/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kompactor
-Version: 0.7.3
+Version: 0.7.4
 Summary: Cut the tokens Claude Code spends on noise: compacted command output (failing runs included), outline-first reads, a local code graph, and per-turn savings.
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/amarkum/kompactor
@@ -21,7 +21,10 @@ Requires-Dist: tiktoken>=0.7; extra == "exact"
 Dynamic: license-file
 <p align="center">
-  <img src="https://raw.githubusercontent.com/amarkum/kompactor/main/docs/brand/kompactor-logo-light.png" alt="Kompactor" width="240">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/amarkum/kompactor/main/docs/brand/kompactor-logo-dark.png">
+    <img src="https://raw.githubusercontent.com/amarkum/kompactor/main/docs/brand/kompactor-logo-light.png" alt="Kompactor" width="240">
+  </picture>
 </p>
 <p align="center"><b>Cut the tokens Claude Code spends on noise.</b><br>
@@ -39,7 +42,7 @@ Most of a Claude Code session's tokens aren't your prompt or Claude's answer. Th
 ## Contents
-[Install](#install) · [After you install](#after-you-install) · [How it works](#how-it-works) · [Use it from Claude Code](#use-it-from-claude-code) · [Quality vs tokens](#quality-vs-tokens) · [See your savings](#see-your-savings) · [Turn it off](#turn-it-off-or-remove-it) · [Evidence](#evidence) · [Code graph](#code-graph) · [Teams](#use-it-across-a-team) · [Commands](#commands)
+[Install](#install) · [After you install](#after-you-install) · [How it works](#how-it-works) · [Examples](#examples) · [Use it from Claude Code](#use-it-from-claude-code) · [Quality vs tokens](#quality-vs-tokens) · [See your savings](#see-your-savings) · [Turn it off](#turn-it-off-or-remove-it) · [What it runs and changes](#what-kompactor-runs-and-changes) · [Evidence](#evidence) · [Code graph](#code-graph) · [Teams](#use-it-across-a-team) · [Troubleshooting](#troubleshooting) · [Commands](#commands) · [Support](#support-and-security)
 ## Install
@@ -59,7 +62,7 @@ pipx install kompactor        # or: pip install kompactor · uv tool install kom
 kompactor setup
 ```
-**VS Code.** Download `kompactor-0.7.3.vsix` from [Releases](https://github.com/amarkum/kompactor/releases), install it (Extensions › `⋯` › *Install from VSIX…*), and click **Enable** when Kompactor asks.
+**VS Code.** Download `kompactor-0.7.4.vsix` from [Releases](https://github.com/amarkum/kompactor/releases), install it (Extensions › `⋯` › *Install from VSIX…*), and click **Enable** when Kompactor asks.
 ## After you install
@@ -67,7 +70,7 @@ kompactor setup
 2. **Work as usual.** You don't call Kompactor; it acts on Claude's tool calls by itself. After each reply you'll see a line such as `Kompactor: −8.2k tokens this turn`, and the status line shows the running total.
 3. **Check it's on:** run `kompactor` in a terminal (or `/kompactor` in Claude Code). It shows whether it's on, your level, savings so far and how to change things:
    ```
-   Kompactor 0.7.3: ON
+   Kompactor 0.7.4: ON
      Connected via the Claude Code plugin. New Claude Code sessions are compacted.
      Level: Balanced (level 3 of 5). Change it: `kompactor config preset 1-5`, the dashboard, or /kompactor balanced
      Saved so far: 41.3k tokens (−38%) over 52 tool calls. Details: `kompactor gain`
@@ -88,6 +91,18 @@ Kompactor uses Claude Code's hooks, so it sits between Claude's tools and Claude
 **Nothing is lost.** Every shortened output keeps a raw copy that Claude can fetch with `kompactor show <id>`. Kompactor never changes what a command does, your permission rules still apply, and if anything goes wrong it lets the original output through. Everything runs on your machine; nothing is sent anywhere ([privacy](https://github.com/amarkum/kompactor/blob/main/PRIVACY.md)).
+## Examples
+Ask Claude Code the way you normally would. These prompts come from the [evidence](#evidence) runs:
+| You ask | What Kompactor does | Measured |
+|---|---|---|
+| "Run the tests and tell me which one fails and why." | Claude sees the failing test, its error and the summary line instead of hundreds of passing tests, even when the run exits non-zero. | Go: −33% tokens; vitest: −37% cost |
+| "Where is the session cookie signed?" | Big files arrive as outlines with line ranges, and the first search adds a short map of the main modules, so Claude finds the code in fewer turns. | Flask: −26% tokens |
+| "Install the dependencies and check that it builds." | Download and progress chatter is dropped; warnings, errors and the result are kept. | `npm install`: ~33,000 › 469 tokens |
+| "What does changing `createStore` affect?" | The code graph lists the files that use it and the tests to run. | 27/27 answers correct |
+| `/kompactor review` | Lists cuts in your current diff: duplicated helpers, unused options, dead branches. | |
 ## Use it from Claude Code
 Type these in any Claude Code chat:
@@ -140,6 +155,20 @@ kompactor uninstall   # remove hooks, status line, shell prefix and skill (add -
 ```
 Then remove the package the way you installed it: `claude plugin uninstall kompactor`, `pipx uninstall kompactor`, or uninstall the extension in VS Code. Setup never replaces a status line or shell prefix you already had, and keeps a backup in `~/.claude/settings.json.kompactor-backup`.
+## What Kompactor runs and changes
+Everything below happens on your machine. Kompactor makes no network requests of its own and has no telemetry. (If you install the optional `tiktoken` package for exact token counts, tiktoken downloads its token table once, on first use.)
+**What it runs.** Python hooks that Claude Code calls (`python3 kompactor/_launch.py hook <name>` from the plugin folder): after Bash, Read, Grep, Glob and edit tool calls; before Read; at session start, subagent start and before compaction; and when a turn ends. After `/kompactor setup` on macOS and Linux, Claude's Bash commands run through Kompactor's shell prefix (`~/.kompactor/bin/kompactor-shell`) so failing runs can be compacted too. The prefix runs after Claude Code's permission check, on Claude's original command, and returns its exit code unchanged.
+**What it adds to Claude's context.** Compacted tool output, outlines in place of large file reads, a code map once per session, a one-line savings note after each turn, and short reply rules at session start and for subagents. The rules are plain text you can read in [`kompactor/rules.py`](https://github.com/amarkum/kompactor/blob/main/kompactor/rules.py); the level decides which ones apply (none at level 1).
+**What it reads.** The tool output Claude Code passes to its hooks, the files Claude reads (to outline them), your project's source (for the code graph), and the context size Claude Code gives the status line. Hooks never read your session transcripts. `kompactor estimate` and the dashboard's **Replay your history** panel read your local Claude Code session logs in `~/.claude/projects`, only when you run them, to show what Kompactor would have saved; the result isn't stored or sent anywhere.
+**What it writes.** `~/.kompactor/`: settings, the savings ledger, raw copies of shortened output (for `kompactor show`), the code graph index and the `~/.kompactor/bin/` launchers (written at session start). History is deleted after 30 days by default (`retention_days`). Setup edits `~/.claude/settings.json` to add Kompactor's hooks (non-plugin installs), a status line (only if you have none) and `CLAUDE_CODE_SHELL_PREFIX` (only if it isn't set), keeping a backup in `settings.json.kompactor-backup`; non-plugin installs also get the `/kompactor` skill in `~/.claude/skills`. Nothing is written to your repositories.
+**What it never does.** Change your permission rules or sandbox settings, change what a command does, or send your code or output anywhere. Details: [privacy policy](https://github.com/amarkum/kompactor/blob/main/PRIVACY.md).
 ## Evidence
 `kompactor prove` runs each task in real headless Claude Code sessions (`claude -p`), 3 times without Kompactor and 3 times with it, interleaved, with the same prompt, tools, turn limit and budget cap. Tokens are input + cache writes + cache reads + output across every API call; cost is Claude Code's own figure.
@@ -218,7 +247,17 @@ When a teammate trusts the folder, Claude Code installs the plugin; each person
 { "preset": 4, "overrides": { "never_compact": ["terraform plan"] } }
 ```
-**Admins** can put the same keys in Claude Code's managed settings to roll it out to every machine. To control what your team runs, fork the repo and use `your-org/kompactor` in the commands above. The [usage guide](https://github.com/amarkum/kompactor/blob/main/docs/usage.html) (also in the dashboard as **Guide**) covers rollout, troubleshooting and FAQs.
+**Admins** can put the same keys in Claude Code's managed settings to roll it out to every machine. To control what your team runs, fork the repo and use `your-org/kompactor` in the commands above. The dashboard's **Guide** page covers rollout, settings and FAQs in more detail.
+## Troubleshooting
+| Problem | What to do |
+|---|---|
+| No savings line after replies | Restart Claude Code after setup, then run `kompactor doctor`: it checks the installation and shows recent hook errors. The dashboard's **Self-test** panel runs every hook once. |
+| An output looks too short | Claude can fetch the original with `kompactor show <id>` (the id is in the shortened output), or search earlier outputs with `kompactor search "text"`. |
+| A command should never be shortened | Add it to **Never compact these commands** on the dashboard, or in `.kompactor.json` (`"never_compact": ["terraform plan"]`). For a single run, start the command with `KOMPACTOR_RAW=1`. |
+| Something seems off | `kompactor stop` turns Kompactor off at once; every hook also lets the original output through if it hits an error. Errors are logged to `~/.kompactor/hook-errors.log`. |
+| The dashboard port is busy | `kompactor start` picks a free port by itself and prints the address. |
 ## Commands
@@ -239,7 +278,7 @@ kompactor ui                      the dashboard, in the foreground
 ## Development
 ```bash
-python -m unittest discover tests     # 81 tests, including the real shell prefix run as Claude Code runs it
+python -m unittest discover tests     # 80 tests, including the real shell prefix run as Claude Code runs it
 node vscode/test/smoke.js             # VS Code extension against a mock API
 ./scripts/build-vsix.sh               # › dist/kompactor-<version>.vsix
 python scripts/bump_version.py X.Y.Z  # bump every version; pushing to main publishes to PyPI
@@ -249,4 +288,10 @@ How Claude Code's hooks behave on success, failure and very long output, and why
 Kompactor was called Kompact until version 0.4; installing it replaces an old Kompact install's settings.
-[Privacy](https://github.com/amarkum/kompactor/blob/main/PRIVACY.md) · [MIT License](https://github.com/amarkum/kompactor/blob/main/LICENSE)
+## Support and security
+- **Questions, bugs and ideas:** [open an issue](https://github.com/amarkum/kompactor/issues).
+- **Security problems:** please report them privately, as described in [SECURITY.md](https://github.com/amarkum/kompactor/blob/main/SECURITY.md).
+- **Privacy:** [PRIVACY.md](https://github.com/amarkum/kompactor/blob/main/PRIVACY.md) explains what Kompactor stores and how to delete it.
+[MIT License](https://github.com/amarkum/kompactor/blob/main/LICENSE)

{kompactor-0.7.3 → kompactor-0.7.4}/pyproject.toml RENAMED Viewed

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "kompactor"
-version = "0.7.3"
+version = "0.7.4"
 description = "Cut the tokens Claude Code spends on noise: compacted command output (failing runs included), outline-first reads, a local code graph, and per-turn savings."
 readme = "README.md"
 requires-python = ">=3.9"

{kompactor-0.7.3 → kompactor-0.7.4}/tests/test_kompactor.py RENAMED Viewed

@@ -435,12 +435,6 @@ class PresetAndLanguageTests(unittest.TestCase):
 class DocsTests(unittest.TestCase):
-    def test_docs_copy_in_sync(self):
-        import subprocess
-        root = Path(__file__).resolve().parent.parent
-        self.assertEqual(subprocess.run([sys.executable, str(root / "scripts/sync_docs.py"), "--check"]).returncode, 0,
-                         "docs/usage.html is stale: run python scripts/sync_docs.py")
     def test_versions_agree(self):
         root = Path(__file__).resolve().parent.parent
         import re as _re
@@ -469,9 +463,15 @@ class TurnAndSetupTests(unittest.TestCase):
         ev = {"session_id": "turn1", "tool_input": {"command": "git log"}, "cwd": TMP,
               "tool_response": {"stdout": GIT_LOG, "stderr": "", "interrupted": False, "isImage": False}}
         run_hook("post-bash", ev)
+        from kompactor import cli
+        # Claude Code tells the status line how big the context is; Kompactor records that number
+        sys.stdin = io.StringIO(json.dumps({"session_id": "turn1", "workspace": {"current_dir": TMP},
+                                            "context_window": {"total_input_tokens": 21000}}))
+        with redirect_stdout(io.StringIO()):
+            cli.main(["statusline"])
+        # ...and never reads the session transcript, even when the event names one
         transcript = Path(TMP, "t.jsonl")
-        transcript.write_text(json.dumps({"type": "assistant", "message": {"usage": {
-            "input_tokens": 5, "cache_read_input_tokens": 20000, "cache_creation_input_tokens": 995}}}) + "\n")
+        transcript.write_text(json.dumps({"type": "assistant", "message": {"usage": {"input_tokens": 99999}}}) + "\n")
         sys.stdin = io.StringIO(json.dumps({"session_id": "turn1", "transcript_path": str(transcript), "cwd": TMP}))
         buf = io.StringIO()
         with redirect_stdout(buf):
@@ -482,7 +482,6 @@ class TurnAndSetupTests(unittest.TestCase):
         self.assertIn("context ≈", msg)
         live = store.read_live()
         self.assertEqual(live["session"], "turn1")
-        from kompactor import cli
         sys.stdin = io.StringIO(json.dumps({"session_id": "turn1", "workspace": {"current_dir": TMP}}))
         buf = io.StringIO()
         with redirect_stdout(buf):
@@ -558,7 +557,7 @@ class SourceTests(unittest.TestCase):
     """The dashboard shows teammates install commands for the public repo, or a fork named by KOMPACTOR_REPO."""
     def test_parse_source(self):
-        self.assertEqual(installer.parse_source("https://ghp_secret@github.com/acme/kompactor.git"),
+        self.assertEqual(installer.parse_source("https://someone@github.com/acme/kompactor.git"),
                          {"repo": "acme/kompactor", "clone": "https://github.com/acme/kompactor.git",
                           "marketplace": "acme/kompactor", "dir": "kompactor"})
         self.assertEqual(installer.parse_source("git@github.com:acme/kompactor.git")["marketplace"], "acme/kompactor")
@@ -567,13 +566,9 @@ class SourceTests(unittest.TestCase):
         self.assertEqual(installer.parse_source(""), {})
     def test_source_defaults_to_the_public_repo(self):
-        from unittest import mock
-        with mock.patch.dict(os.environ, {"KOMPACTOR_REPO": ""}):
-            self.assertEqual(installer.source()["marketplace"], "amarkum/kompactor")
-        with mock.patch.dict(os.environ, {"KOMPACTOR_REPO": "acme/kompactor"}):  # a team's fork
-            self.assertEqual(installer.source()["clone"], "https://github.com/acme/kompactor.git")
-        with mock.patch.dict(os.environ, {"KOMPACTOR_REPO": "https://ghp_x@git.acme.dev/tools/kompactor.git"}):
-            self.assertNotIn("ghp_x", json.dumps(installer.source()))
+        self.assertEqual(installer.source("")["marketplace"], "amarkum/kompactor")
+        self.assertEqual(installer.source("acme/kompactor")["clone"], "https://github.com/acme/kompactor.git")  # a fork
+        self.assertNotIn("someone@", json.dumps(installer.source("https://someone@git.acme.dev/tools/kompactor.git")))
 if __name__ == "__main__":