kompactor 0.8.2__tar.gz → 0.8.3__tar.gz

{kompactor-0.8.2 → kompactor-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kompactor
-Version: 0.8.2
+Version: 0.8.3
 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
@@ -123,7 +123,7 @@ kompactor start
 ```
 If your shell says `kompactor: command not found` (pip put the command in a folder that isn't on your PATH), run `python3 -m kompactor start` once. It links `kompactor` into a folder that is already on your PATH, such as `~/.local/bin`, so the command works in every terminal from then on.
 
-**VS Code and Cursor.** `kompactor start` adds the Kompactor extension to VS Code and Cursor automatically when they're installed (skip it with `--no-editor`); reload the window and a **Kompactor** icon appears in the activity bar. To install it by hand, download `kompactor-0.8.2.vsix` from [Releases](https://github.com/amarkum/kompactor/releases) and use Extensions › `⋯` › *Install from VSIX…*.
+**VS Code and Cursor.** `kompactor start` adds the Kompactor extension to VS Code and Cursor automatically when they're installed (skip it with `--no-editor`); reload the window and a **Kompactor** icon appears in the activity bar. To install it by hand, download `kompactor-0.8.3.vsix` from [Releases](https://github.com/amarkum/kompactor/releases) and use Extensions › `⋯` › *Install from VSIX…*.
 
 **From source:**
 ```bash
@@ -136,12 +136,15 @@ git clone https://github.com/amarkum/kompactor.git && ./kompactor/install.sh
 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 like `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):
    ```
-   Kompactor 0.8.2: 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`
+   Kompactor 0.8.3 is on
+
+     Claude Code   connected
+     Level         Balanced (3 of 5)
+     Saved         41.3k tokens (−38%) in 52 tool calls
+     Dashboard     http://127.0.0.1:56710/
    ```
-4. **In VS Code or Cursor:** click the **Kompactor** icon in the activity bar for tokens and estimated dollars saved this session, in this project, today and over 30 days, plus what every recent turn saved.
+   `kompactor help` lists every command.
+4. **In VS Code or Cursor:** click the **Kompactor** icon in the activity bar for tokens and estimated dollars saved this session, in this project, today and over 30 days, plus what Kompactor shortened in each of Claude's recent replies.
 5. **Three commands to remember:** `kompactor start` turns it on and opens the dashboard, `kompactor stop` pauses it, `kompactor uninstall` removes it.
 
 ## How it works

{kompactor-0.8.2 → kompactor-0.8.3}/README.md

@@ -90,7 +90,7 @@ kompactor start
 ```
 If your shell says `kompactor: command not found` (pip put the command in a folder that isn't on your PATH), run `python3 -m kompactor start` once. It links `kompactor` into a folder that is already on your PATH, such as `~/.local/bin`, so the command works in every terminal from then on.
 
-**VS Code and Cursor.** `kompactor start` adds the Kompactor extension to VS Code and Cursor automatically when they're installed (skip it with `--no-editor`); reload the window and a **Kompactor** icon appears in the activity bar. To install it by hand, download `kompactor-0.8.2.vsix` from [Releases](https://github.com/amarkum/kompactor/releases) and use Extensions › `⋯` › *Install from VSIX…*.
+**VS Code and Cursor.** `kompactor start` adds the Kompactor extension to VS Code and Cursor automatically when they're installed (skip it with `--no-editor`); reload the window and a **Kompactor** icon appears in the activity bar. To install it by hand, download `kompactor-0.8.3.vsix` from [Releases](https://github.com/amarkum/kompactor/releases) and use Extensions › `⋯` › *Install from VSIX…*.
 
 **From source:**
 ```bash
@@ -103,12 +103,15 @@ git clone https://github.com/amarkum/kompactor.git && ./kompactor/install.sh
 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 like `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):
    ```
-   Kompactor 0.8.2: 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`
+   Kompactor 0.8.3 is on
+
+     Claude Code   connected
+     Level         Balanced (3 of 5)
+     Saved         41.3k tokens (−38%) in 52 tool calls
+     Dashboard     http://127.0.0.1:56710/
    ```
-4. **In VS Code or Cursor:** click the **Kompactor** icon in the activity bar for tokens and estimated dollars saved this session, in this project, today and over 30 days, plus what every recent turn saved.
+   `kompactor help` lists every command.
+4. **In VS Code or Cursor:** click the **Kompactor** icon in the activity bar for tokens and estimated dollars saved this session, in this project, today and over 30 days, plus what Kompactor shortened in each of Claude's recent replies.
 5. **Three commands to remember:** `kompactor start` turns it on and opens the dashboard, `kompactor stop` pauses it, `kompactor uninstall` removes it.
 
 ## How it works

{kompactor-0.8.2 → kompactor-0.8.3}/kompactor/__init__.py

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

{kompactor-0.8.2 → kompactor-0.8.3}/kompactor/cli.py

@@ -190,47 +190,36 @@ def cmd_status(a):
     """What Kompactor is doing right now, and what to do next. Also what plain `kompactor` prints."""
     st = installer.status()
     cfg = config.load(os.getcwd())
-    level = f"{config.PRESETS[cfg['preset']]['name']} (level {cfg['preset']} of 5)"
-    on = (st["plugin_enabled"] or st["hooks_installed"]) and not store.paused()
-    state = ("ON" if on else "STOPPED" if store.paused() else "NOT SET UP")
-    print(f"Kompactor {__version__}: {state}")
-    if not (st["plugin_enabled"] or st["hooks_installed"]):
-        print("  Run `kompactor start` to connect it to Claude Code (CLI and VS Code).")
+    connected = st["plugin_enabled"] or st["hooks_installed"]
+    state = "on" if connected and not store.paused() else "stopped" if connected else "not set up"
+    if not connected:
+        claude = "not connected; run 'kompactor start'"
     elif store.paused():
-        print("  Claude Code output passes through untouched. Turn it back on: `kompactor start`")
+        claude = "paused; run 'kompactor start' to resume"
     else:
-        print(f"  Connected via {'the Claude Code plugin' if st['plugin_enabled'] else st['settings_file']}."
-              " New Claude Code sessions are compacted.")
-    print(f"  Level: {level}. Change it: `kompactor config preset 1-5`, the dashboard, or /kompactor balanced")
+        claude = "connected (plugin)" if st["plugin_enabled"] else "connected"
     with store.connect() as db:
         raw, kept, n = db.execute("SELECT COALESCE(SUM(raw_tokens),0), COALESCE(SUM(kept_tokens),0), COUNT(*) "
                                   "FROM events").fetchone()
-    if n:
-        print(f"  Saved so far: {_fmt(raw - kept)} tokens ({_pct(raw - kept, raw)}) over {n} tool calls."
-              " Details: `kompactor gain`")
-    else:
-        print("  Saved so far: nothing yet. Use Claude Code as usual; the status line shows savings per turn.")
+    saved = f"{_fmt(raw - kept)} tokens ({_pct(raw - kept, raw)}) in {n} tool calls" if n else "nothing yet"
     d = _dashboard()
-    print(f"  Dashboard: {d['url'] if d else 'not running (`kompactor start` opens it)'}")
-    print(f"""
-How it works
-  Kompactor sits between Claude Code's tools and Claude. Long command output (test runs, installs,
-  git log), big file reads and searches are shortened before Claude reads them: errors, failing tests,
-  your own stack frames and summary lines are always kept. Claude can still get the full text with
-  `kompactor show <id>`. You don't change how you work; just use Claude Code.
-
-Use it from Claude Code
-  /kompactor status · /kompactor max savings · /kompactor balanced · /kompactor stop · /kompactor start
-
-Turn it off
-  kompactor stop        pause it (settings kept); `kompactor start` resumes
-  kompactor uninstall   remove it from Claude Code, VS Code and Cursor, and delete its data
-
-Evidence
-  Measured A/B runs of real Claude Code tasks: {EVIDENCE_URL}
-  Your own sessions: `kompactor estimate` replays them and shows what it would have saved.
-
-All commands: kompactor --help""")
+    print(f"""Kompactor {__version__} is {state}
+
+  Claude Code   {claude}
+  Level         {config.PRESETS[cfg['preset']]['name']} ({cfg['preset']} of 5)
+  Saved         {saved}
+  Dashboard     {d['url'] if d else "not running"}
+
+Commands:
+  start         Turn Kompactor on and open the dashboard
+  stop          Pause Kompactor (settings are kept)
+  uninstall     Remove Kompactor and delete its data
+  gain          Show what it saved, command by command
+  help          List all commands
+
+Kompactor shortens test runs, installs, logs and big file reads
+before Claude reads them, keeping every error, failure and summary.
+Evidence: {EVIDENCE_URL}""")
     return 0
 
 
@@ -486,16 +475,59 @@ def cmd_doctor(a):
     return 0
 
 
+HELP = """Kompactor {version}: cut the tokens Claude Code spends on noise
+
+Usage:
+  kompactor <command> [options]
+
+Getting started:
+  start         Turn Kompactor on and open the dashboard
+  stop          Pause Kompactor (settings are kept)
+  uninstall     Remove Kompactor and delete its data
+  status        Show whether it's on and what it saved
+
+Savings:
+  gain          Show what it saved, command by command
+  estimate      Estimate savings on your past sessions
+  ui            Open the dashboard in this terminal
+
+Settings:
+  presets       List the quality-vs-tokens levels
+  config        Show or change settings
+
+Code:
+  graph         Find code, callers and the impact of a change
+  outline       List a file's symbols with line ranges
+  symbol        Print one definition
+  show          Print an output Kompactor shortened
+  search        Search outputs Kompactor shortened
+
+Other:
+  run           Run a command and print its compacted output
+  doctor        Check the installation
+  prove         A/B test Kompactor in Claude Code sessions
+
+Options:
+  -h, --help    Show this help
+  --version     Show the version
+
+Run 'kompactor <command> --help' for details on a command.
+Docs: https://github.com/amarkum/kompactor"""
+
+
 def main(argv=None):
     argv = sys.argv[1:] if argv is None else argv
     if argv[:1] == ["setup"]:  # the old name for `start`; older docs still say it
         argv = ["start"] + ["--no-browser" if x == "--no-ui" else x for x in argv[1:]]
+    if argv[:1] in (["help"], ["-h"], ["--help"]):
+        print(HELP.format(version=__version__))
+        return 0
     if argv[:1] == ["prove"]:  # has its own parser
         from . import prove
         return prove.main(argv[1:])
     ap = argparse.ArgumentParser(prog="kompactor", description="Cut the tokens Claude Code spends on noise.")
     ap.add_argument("--version", action="version", version=__version__)
-    sp = ap.add_subparsers(dest="cmd")
+    sp = ap.add_subparsers(dest="cmd", metavar="<command>")
 
     p = sp.add_parser("status", help="is it on, your level, savings so far, and how to use it (also: plain `kompactor`)")
     p.set_defaults(fn=cmd_status)
@@ -543,7 +575,7 @@ def main(argv=None):
                    help="don't set CLAUDE_CODE_SHELL_PREFIX (then commands that fail are not compacted)")
     p.set_defaults(fn=cmd_install)
 
-    p = sp.add_parser("statusline", help="(internal) Claude Code status line")
+    p = sp.add_parser("statusline")  # internal: Claude Code's status line
     p.set_defaults(fn=cmd_statusline)
 
     p = sp.add_parser("map", help="ranked repo skeleton within a token budget")
@@ -606,13 +638,20 @@ def main(argv=None):
     p.add_argument("--json", action="store_true")
     p.set_defaults(fn=cmd_presets)
 
-    p = sp.add_parser("hook", help="(internal) Claude Code hook entrypoint")
+    p = sp.add_parser("hook")  # internal: Claude Code hook entry point
     p.add_argument("name", choices=list(hooks.HANDLERS))
     p.set_defaults(fn=cmd_hook)
 
     p = sp.add_parser("doctor", help="check installation")
     p.set_defaults(fn=cmd_doctor)
 
+    if argv and not argv[0].startswith("-") and argv[0] not in sp.choices:
+        import difflib
+        near = difflib.get_close_matches(argv[0], [c for c in sp.choices if c not in ("hook", "statusline")], n=1)
+        print(f"kompactor: unknown command '{argv[0]}'" + (f"\n\nDid you mean this?\n  kompactor {near[0]}" if near else ""),
+              file=sys.stderr)
+        print("\nRun 'kompactor help' for a list of commands.", file=sys.stderr)
+        return 2
     a = ap.parse_args(argv)
     if not a.cmd:
         a.fn = cmd_status

{kompactor-0.8.2 → kompactor-0.8.3}/kompactor/static/usage.html

@@ -139,7 +139,7 @@ svg.chev { width: 11px; height: 11px; stroke: var(--ink-3); fill: none; stroke-w
           <pre><code>pipx install kompactor
 kompactor start</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.8.2.vsix</code></pre></div>
+          <pre><code>code --install-extension kompactor-0.8.3.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"><code>kompactor start</code> 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.8.2 → kompactor-0.8.3}/kompactor/store.py

@@ -160,8 +160,18 @@ def savings(price_per_mtok: float = 3.0, session: str = "", project: str = "") -
         if project:
             periods["project"] = total("project = ?", (project,))
         recent = db.execute("SELECT session, idx, ts, raw_tokens, kept_tokens, features FROM turns "
-                            "WHERE project = ? OR (? = '' AND session = ?) ORDER BY ts DESC LIMIT 12",
+                            "WHERE project = ? OR (? = '' AND session = ?) ORDER BY ts DESC LIMIT 30",
                             (project, project, session)).fetchall()
+        shortened = {}  # what each recent reply shortened: its commands and files, biggest first
+        for s, idx, ts, *_ in recent:
+            prev = db.execute("SELECT COALESCE(MAX(ts), 0) FROM turns WHERE session = ? AND idx < ?", (s, idx)).fetchone()[0]
+            items = {}
+            for f, d, r, k in db.execute("SELECT feature, detail, raw_tokens, kept_tokens FROM events WHERE session = ? "
+                                         "AND ts > ? AND ts <= ? AND raw_tokens > kept_tokens", (s, prev, ts)):
+                it = items.setdefault(_label(f, d), {"what": _label(f, d), "saved": 0, "times": 0})
+                it["saved"] += r - k
+                it["times"] += 1
+            shortened[(s, idx)] = sorted(items.values(), key=lambda it: -it["saved"])[:3]
         turns = db.execute("SELECT session, ts, raw_tokens - kept_tokens, project FROM turns "
                            "ORDER BY session, idx").fetchall()
         top = db.execute("SELECT detail, COUNT(*), SUM(raw_tokens), SUM(kept_tokens) FROM events WHERE feature='bash' "
@@ -183,7 +193,13 @@ def savings(price_per_mtok: float = 3.0, session: str = "", project: str = "") -
     return {"price_per_mtok": price_per_mtok, "sessions": sessions, **periods,
             "top": [{"cmd": t[0], "runs": t[1], "raw": t[2], "kept": t[3]} for t in top],
             "turns": [{"session": t[0], "idx": t[1], "ts": t[2], "raw": t[3], "kept": t[4], "saved": t[3] - t[4],
-                       "features": json.loads(t[5] or "{}")} for t in recent]}
+                       "features": json.loads(t[5] or "{}"), "shortened": shortened[(t[0], t[1])]} for t in recent]}
+
+
+def _label(feature: str, detail: str) -> str:
+    """How a saving reads in a list: the command, or the file that was outlined or not re-read."""
+    name = os.path.basename((detail or "").split(" (")[0])
+    return {"read_outline": f"read {name}", "read_dedupe": f"re-read {name}"}.get(feature, detail or feature)
 
 
 def prune(retention_days: float) -> None:

{kompactor-0.8.2 → kompactor-0.8.3}/kompactor.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kompactor
-Version: 0.8.2
+Version: 0.8.3
 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
@@ -123,7 +123,7 @@ kompactor start
 ```
 If your shell says `kompactor: command not found` (pip put the command in a folder that isn't on your PATH), run `python3 -m kompactor start` once. It links `kompactor` into a folder that is already on your PATH, such as `~/.local/bin`, so the command works in every terminal from then on.
 
-**VS Code and Cursor.** `kompactor start` adds the Kompactor extension to VS Code and Cursor automatically when they're installed (skip it with `--no-editor`); reload the window and a **Kompactor** icon appears in the activity bar. To install it by hand, download `kompactor-0.8.2.vsix` from [Releases](https://github.com/amarkum/kompactor/releases) and use Extensions › `⋯` › *Install from VSIX…*.
+**VS Code and Cursor.** `kompactor start` adds the Kompactor extension to VS Code and Cursor automatically when they're installed (skip it with `--no-editor`); reload the window and a **Kompactor** icon appears in the activity bar. To install it by hand, download `kompactor-0.8.3.vsix` from [Releases](https://github.com/amarkum/kompactor/releases) and use Extensions › `⋯` › *Install from VSIX…*.
 
 **From source:**
 ```bash
@@ -136,12 +136,15 @@ git clone https://github.com/amarkum/kompactor.git && ./kompactor/install.sh
 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 like `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):
    ```
-   Kompactor 0.8.2: 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`
+   Kompactor 0.8.3 is on
+
+     Claude Code   connected
+     Level         Balanced (3 of 5)
+     Saved         41.3k tokens (−38%) in 52 tool calls
+     Dashboard     http://127.0.0.1:56710/
    ```
-4. **In VS Code or Cursor:** click the **Kompactor** icon in the activity bar for tokens and estimated dollars saved this session, in this project, today and over 30 days, plus what every recent turn saved.
+   `kompactor help` lists every command.
+4. **In VS Code or Cursor:** click the **Kompactor** icon in the activity bar for tokens and estimated dollars saved this session, in this project, today and over 30 days, plus what Kompactor shortened in each of Claude's recent replies.
 5. **Three commands to remember:** `kompactor start` turns it on and opens the dashboard, `kompactor stop` pauses it, `kompactor uninstall` removes it.
 
 ## How it works

{kompactor-0.8.2 → kompactor-0.8.3}/kompactor.egg-info/SOURCES.txt

@@ -35,7 +35,7 @@ kompactor/static/fonts/plex-mono-500.woff2
 kompactor/static/fonts/plex-sans-400.woff2
 kompactor/static/fonts/plex-sans-500.woff2
 kompactor/static/fonts/plex-sans-600.woff2
-kompactor/vsix/kompactor-0.8.2.vsix
+kompactor/vsix/kompactor-0.8.3.vsix
 tests/test_graph.py
 tests/test_kompactor.py
 tests/test_shell.py

{kompactor-0.8.2 → kompactor-0.8.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kompactor"
-version = "0.8.2"
+version = "0.8.3"
 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.8.2 → kompactor-0.8.3}/tests/test_kompactor.py

@@ -16,6 +16,11 @@ installer.PATH_DIRS = ()  # never link `kompactor` into real PATH folders from t
 installer.EDITORS = ()  # never install or remove the real VS Code / Cursor extension from tests
 
 
+def mock_stderr(buf):
+    from contextlib import redirect_stderr
+    return redirect_stderr(buf)
+
+
 def run_hook(name, event):
     sys.stdin = io.StringIO(json.dumps(event))
     buf = io.StringIO()
@@ -608,6 +613,20 @@ exit 0
         self.assertEqual(log.read_text().split("\n")[:2],
                          [f"--install-extension {vsix} --force", "--uninstall-extension kompactor.kompactor"])
 
+    def test_help_and_mistyped_commands(self):
+        from kompactor import cli
+        out = io.StringIO()
+        with redirect_stdout(out):
+            self.assertEqual(cli.main(["help"]), 0)
+        self.assertIn("Usage:\n  kompactor <command> [options]", out.getvalue())
+        self.assertIn("  start         Turn Kompactor on", out.getvalue())
+        self.assertLessEqual(max(len(line) for line in out.getvalue().splitlines()), 80)   # fits a normal terminal
+        self.assertNotIn("statusline", out.getvalue())          # internal commands stay out of the help
+        err = io.StringIO()
+        with mock_stderr(err):
+            self.assertEqual(cli.main(["strt"]), 2)
+        self.assertIn("Did you mean this?\n  kompactor start", err.getvalue())
+
     def test_source_defaults_to_the_public_repo(self):
         self.assertEqual(installer.source("")["marketplace"], "amarkum/kompactor")
         self.assertEqual(installer.source("acme/kompactor")["clone"], "https://github.com/acme/kompactor.git")  # a fork