kompactor 0.7.8__tar.gz → 0.8.0__tar.gz

{kompactor-0.7.8 → kompactor-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kompactor
-Version: 0.7.8
+Version: 0.8.0
 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
@@ -112,17 +112,18 @@ Pick one. All of them set up the same thing, and the Claude Code CLI and VS Code
 ```
 /plugin marketplace add amarkum/kompactor
 /plugin install amarkum@kompactor
-/kompactor setup
+/kompactor start
 ```
-The last step adds the status line and the shell prefix that compacts failing commands, which a plugin can't set itself. Then restart Claude Code.
+The last step turns Kompactor on: it adds the status line and the shell prefix that compacts failing commands (a plugin can't set those itself) and opens the dashboard. Then restart Claude Code.
 
 **pip / pipx / uv** (macOS, Linux, Windows):
 ```bash
 pipx install kompactor        # or: pip install kompactor · uv tool install kompactor
-kompactor setup
+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.** Download `kompactor-0.7.8.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.8.0.vsix` from [Releases](https://github.com/amarkum/kompactor/releases), install it (Extensions › `⋯` › *Install from VSIX…*), and click **Enable** when Kompactor asks.
 
 **From source:**
 ```bash
@@ -135,12 +136,12 @@ 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.7.8: ON
+   Kompactor 0.8.0: 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`
    ```
-4. **Open the dashboard:** `kompactor start` runs it in the background on a free port and prints the address.
+4. **Three commands to remember:** `kompactor start` turns it on and opens the dashboard, `kompactor stop` pauses it, `kompactor uninstall` removes it.
 
 ## How it works
 
@@ -186,10 +187,10 @@ Ask Claude Code the way you normally would. These prompts come from the [evidenc
 
 | Command | What it does |
 |---|---|
+| `kompactor start` | Turn Kompactor on: connect it to Claude Code (CLI + VS Code) and open the dashboard on a free port |
+| `kompactor stop` | Pause it and close the dashboard; settings are kept |
+| `kompactor uninstall [--purge]` | Remove it from Claude Code (`--purge` also deletes `~/.kompactor`) |
 | `kompactor` / `kompactor status` | On or off, level, savings, how it works |
-| `kompactor setup` | Connect to Claude Code (CLI + VS Code) and open the dashboard |
-| `kompactor start` / `kompactor stop` | Turn on (dashboard in the background, free port) / pause |
-| `kompactor uninstall [--purge]` | Remove from Claude Code (`--purge` also deletes `~/.kompactor`) |
 | `kompactor presets` · `kompactor config preset 4` | List levels · change level |
 | `kompactor config <setting> <value>` | Change one [setting](#settings) |
 | `kompactor gain` | Savings so far |
@@ -224,7 +225,7 @@ Settings come from, in increasing priority: the level → your global choices
 | Setting | Type | What it does |
 |---|---|---|
 | `bash` | bool | Compact command output |
-| `bash_wrap` | bool | Compact failing commands too (needs the shell prefix from `kompactor setup`) |
+| `bash_wrap` | bool | Compact failing commands too (needs the shell prefix that `kompactor start` adds) |
 | `bash_plain` | bool | Ask Claude to run commands without `\| head`, `\| tail` or `\| grep`, since Kompactor keeps every failure |
 | `bash_min_tokens` | int | Leave outputs smaller than this untouched |
 | `bash_max_lines` | int | Max lines kept per output (head and tail kept; error lines from the middle always kept) |
@@ -306,7 +307,7 @@ kompactor graph unused                     dead-code candidates
   "enabledPlugins": { "amarkum@kompactor": true }
 }
 ```
-When a teammate trusts the folder, Claude Code installs the plugin; each person then runs `/kompactor setup` once. `autoUpdate` keeps everyone on the latest release. Admins can put the same keys in Claude Code's managed settings to roll it out to every machine, and a team that runs its own fork sets `KOMPACTOR_REPO` so the dashboard shows the fork's commands.
+When a teammate trusts the folder, Claude Code installs the plugin; each person then runs `/kompactor start` once. `autoUpdate` keeps everyone on the latest release. Admins can put the same keys in Claude Code's managed settings to roll it out to every machine, and a team that runs its own fork sets `KOMPACTOR_REPO` so the dashboard shows the fork's commands.
 
 ## Evidence
 
@@ -369,13 +370,13 @@ Command output from any language is compacted. These languages also get language
 
 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 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 start` 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).
 
 **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; 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. History is deleted after 30 days by default. 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 writes.** `~/.kompactor/`: settings, the savings ledger, raw copies of shortened output (for `kompactor show`), the code graph index and the `~/.kompactor/bin/` launchers. When `kompactor` isn't on your PATH, it adds one link to that launcher in a writable folder that already is (`~/.local/bin`, `~/bin`, `/opt/homebrew/bin` or `/usr/local/bin`); it never edits shell files or replaces an existing command, and `kompactor uninstall` removes the link. History is deleted after 30 days by default. `kompactor start` 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).
 
@@ -383,7 +384,8 @@ Everything below happens on your machine. Kompactor makes no network requests of
 
 | 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. |
+| `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 writable folder already on your PATH, such as `~/.local/bin`. Claude Code plugin installs do this at the first session. |
+| No savings line after replies | Restart Claude Code after `kompactor start`, 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>`, 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 to `never_compact` in `.kompactor.json`. 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`. |
@@ -455,5 +457,3 @@ Bug reports, ideas and pull requests are welcome. See [CONTRIBUTING.md](https://
 ## License
 
 [MIT](https://github.com/amarkum/kompactor/blob/main/LICENSE) © The Kompactor authors. The dashboard uses the IBM Plex fonts under the [SIL Open Font License](https://github.com/amarkum/kompactor/blob/main/kompactor/static/fonts/OFL.txt).
-
-Built by [stackcone](https://stackcone.com). Read the story behind it: [Kompactor: Cut the Tokens Claude Code Spends on Noise](https://stackcone.com/blog/posts/kompactor-claude-code-token-saver/).

{kompactor-0.7.8 → kompactor-0.8.0}/README.md

@@ -79,17 +79,18 @@ Pick one. All of them set up the same thing, and the Claude Code CLI and VS Code
 ```
 /plugin marketplace add amarkum/kompactor
 /plugin install amarkum@kompactor
-/kompactor setup
+/kompactor start
 ```
-The last step adds the status line and the shell prefix that compacts failing commands, which a plugin can't set itself. Then restart Claude Code.
+The last step turns Kompactor on: it adds the status line and the shell prefix that compacts failing commands (a plugin can't set those itself) and opens the dashboard. Then restart Claude Code.
 
 **pip / pipx / uv** (macOS, Linux, Windows):
 ```bash
 pipx install kompactor        # or: pip install kompactor · uv tool install kompactor
-kompactor setup
+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.** Download `kompactor-0.7.8.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.8.0.vsix` from [Releases](https://github.com/amarkum/kompactor/releases), install it (Extensions › `⋯` › *Install from VSIX…*), and click **Enable** when Kompactor asks.
 
 **From source:**
 ```bash
@@ -102,12 +103,12 @@ 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.7.8: ON
+   Kompactor 0.8.0: 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`
    ```
-4. **Open the dashboard:** `kompactor start` runs it in the background on a free port and prints the address.
+4. **Three commands to remember:** `kompactor start` turns it on and opens the dashboard, `kompactor stop` pauses it, `kompactor uninstall` removes it.
 
 ## How it works
 
@@ -153,10 +154,10 @@ Ask Claude Code the way you normally would. These prompts come from the [evidenc
 
 | Command | What it does |
 |---|---|
+| `kompactor start` | Turn Kompactor on: connect it to Claude Code (CLI + VS Code) and open the dashboard on a free port |
+| `kompactor stop` | Pause it and close the dashboard; settings are kept |
+| `kompactor uninstall [--purge]` | Remove it from Claude Code (`--purge` also deletes `~/.kompactor`) |
 | `kompactor` / `kompactor status` | On or off, level, savings, how it works |
-| `kompactor setup` | Connect to Claude Code (CLI + VS Code) and open the dashboard |
-| `kompactor start` / `kompactor stop` | Turn on (dashboard in the background, free port) / pause |
-| `kompactor uninstall [--purge]` | Remove from Claude Code (`--purge` also deletes `~/.kompactor`) |
 | `kompactor presets` · `kompactor config preset 4` | List levels · change level |
 | `kompactor config <setting> <value>` | Change one [setting](#settings) |
 | `kompactor gain` | Savings so far |
@@ -191,7 +192,7 @@ Settings come from, in increasing priority: the level → your global choices
 | Setting | Type | What it does |
 |---|---|---|
 | `bash` | bool | Compact command output |
-| `bash_wrap` | bool | Compact failing commands too (needs the shell prefix from `kompactor setup`) |
+| `bash_wrap` | bool | Compact failing commands too (needs the shell prefix that `kompactor start` adds) |
 | `bash_plain` | bool | Ask Claude to run commands without `\| head`, `\| tail` or `\| grep`, since Kompactor keeps every failure |
 | `bash_min_tokens` | int | Leave outputs smaller than this untouched |
 | `bash_max_lines` | int | Max lines kept per output (head and tail kept; error lines from the middle always kept) |
@@ -273,7 +274,7 @@ kompactor graph unused                     dead-code candidates
   "enabledPlugins": { "amarkum@kompactor": true }
 }
 ```
-When a teammate trusts the folder, Claude Code installs the plugin; each person then runs `/kompactor setup` once. `autoUpdate` keeps everyone on the latest release. Admins can put the same keys in Claude Code's managed settings to roll it out to every machine, and a team that runs its own fork sets `KOMPACTOR_REPO` so the dashboard shows the fork's commands.
+When a teammate trusts the folder, Claude Code installs the plugin; each person then runs `/kompactor start` once. `autoUpdate` keeps everyone on the latest release. Admins can put the same keys in Claude Code's managed settings to roll it out to every machine, and a team that runs its own fork sets `KOMPACTOR_REPO` so the dashboard shows the fork's commands.
 
 ## Evidence
 
@@ -336,13 +337,13 @@ Command output from any language is compacted. These languages also get language
 
 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 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 start` 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).
 
 **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; 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. History is deleted after 30 days by default. 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 writes.** `~/.kompactor/`: settings, the savings ledger, raw copies of shortened output (for `kompactor show`), the code graph index and the `~/.kompactor/bin/` launchers. When `kompactor` isn't on your PATH, it adds one link to that launcher in a writable folder that already is (`~/.local/bin`, `~/bin`, `/opt/homebrew/bin` or `/usr/local/bin`); it never edits shell files or replaces an existing command, and `kompactor uninstall` removes the link. History is deleted after 30 days by default. `kompactor start` 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).
 
@@ -350,7 +351,8 @@ Everything below happens on your machine. Kompactor makes no network requests of
 
 | 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. |
+| `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 writable folder already on your PATH, such as `~/.local/bin`. Claude Code plugin installs do this at the first session. |
+| No savings line after replies | Restart Claude Code after `kompactor start`, 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>`, 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 to `never_compact` in `.kompactor.json`. 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`. |
@@ -422,5 +424,3 @@ Bug reports, ideas and pull requests are welcome. See [CONTRIBUTING.md](https://
 ## License
 
 [MIT](https://github.com/amarkum/kompactor/blob/main/LICENSE) © The Kompactor authors. The dashboard uses the IBM Plex fonts under the [SIL Open Font License](https://github.com/amarkum/kompactor/blob/main/kompactor/static/fonts/OFL.txt).
-
-Built by [stackcone](https://stackcone.com). Read the story behind it: [Kompactor: Cut the Tokens Claude Code Spends on Noise](https://stackcone.com/blog/posts/kompactor-claude-code-token-saver/).

{kompactor-0.7.8 → kompactor-0.8.0}/kompactor/__init__.py

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

{kompactor-0.7.8 → kompactor-0.8.0}/kompactor/cli.py

@@ -189,7 +189,7 @@ def cmd_status(a):
     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 setup` to connect it to Claude Code (CLI and VS Code).")
+        print("  Run `kompactor start` to connect it to Claude Code (CLI and VS Code).")
     elif store.paused():
         print("  Claude Code output passes through untouched. Turn it back on: `kompactor start`")
     else:
@@ -282,27 +282,15 @@ def _prefix_note(st):
     note = {"kompactor": "Shell prefix: on (failing tests and builds are compacted too)",
             "other": "Shell prefix: another tool already sets CLAUDE_CODE_SHELL_PREFIX, so failing commands are "
                      "not compacted",
-            "missing": "Shell prefix: its script is missing; run `kompactor setup` again",
+            "missing": "Shell prefix: its script is missing; run `kompactor start` again",
             "none": "Shell prefix: off (only commands that succeed are compacted)"}[st["shell_prefix"]]
     print(f"  {note}")
 
 
-def cmd_setup(a):
-    """One-step setup: enable hooks for CLI + VS Code, then open the dashboard."""
-    target = installer.install(statusline=config.read_file()["general"].get("statusline", True))
-    st = installer.status()
-    print("✓ Kompactor plugin is enabled; hooks are active." if st["plugin_enabled"] else f"✓ Hooks installed in {target}")
-    print(f"  Claude Code CLI:   {'found' if st['claude_cli'] else 'not found'}")
-    print(f"  VS Code extension: {st['vscode_extension'] or 'not found'} (uses the same settings)")
-    _prefix_note(st)
-    print("\nNext: restart Claude Code, then work as usual. The status line shows what each turn saved.")
-    print("  `kompactor` shows status and how it works · `kompactor stop` turns it off · "
-          "`kompactor uninstall` removes it")
-    if a.no_ui:
-        return 0
-    print("Opening the dashboard to choose your quality level…")
-    a.no_browser = False
-    return cmd_start(a)
+def _path_note(link):
+    if link:
+        where = os.path.dirname(link).replace(os.path.expanduser("~"), "~", 1)
+        print(f"  Added the `kompactor` command to {where}, so it works in any terminal.")
 
 
 def _pidfile():
@@ -336,12 +324,19 @@ def _kill_dashboard() -> bool:
 
 
 def cmd_start(a):
-    """Turn compaction on and run the dashboard in the background on a free port; returns at once."""
+    """Turn Kompactor on: connect it to Claude Code (hooks, status line, shell prefix), make the
+    `kompactor` command reachable, and run the dashboard in the background on a free port.
+    Returns at once; running it again is safe."""
     (store.home() / "paused").unlink(missing_ok=True)
+    before = installer.status()
+    was_connected = before["plugin_enabled"] or before["hooks_installed"]
+    installer.install(statusline=config.read_file()["general"].get("statusline", True))
     st = installer.status()
-    if not st["plugin_enabled"] and not st["hooks_installed"]:
-        installer.install(statusline=config.read_file()["general"].get("statusline", True))
     print("✓ Kompactor is on: new Claude Code sessions are compacted.")
+    where = st["settings_file"].replace(os.path.expanduser("~"), "~", 1)
+    print(f"  Connected via {'the Claude Code plugin' if st['plugin_enabled'] else where}")
+    _prefix_note(st)
+    _path_note(installer.link_on_path())
     d = _dashboard()
     if not d:
         from . import server
@@ -361,6 +356,8 @@ def cmd_start(a):
         d = {"pid": proc.pid, "url": f"http://127.0.0.1:{port}/"}
         _pidfile().write_text(json.dumps(d))
     print(f"  Dashboard: {d['url']}  (stop with `kompactor stop`)")
+    if not was_connected:
+        print("  Restart Claude Code so sessions that are already open use it too.")
     if not a.no_browser:
         import webbrowser
         webbrowser.open(d["url"])
@@ -478,6 +475,8 @@ def cmd_doctor(a):
 
 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] == ["prove"]:  # has its own parser
         from . import prove
         return prove.main(argv[1:])
@@ -488,6 +487,18 @@ def main(argv=None):
     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)
 
+    p = sp.add_parser("start", help="turn Kompactor on: connect it to Claude Code and open the dashboard")
+    p.add_argument("--port", type=int, default=0, help="preferred port (default: any free port)")
+    p.add_argument("--no-browser", action="store_true")
+    p.set_defaults(fn=cmd_start)
+
+    p = sp.add_parser("stop", help="pause Kompactor and close the dashboard (settings are kept)")
+    p.set_defaults(fn=cmd_stop)
+
+    p = sp.add_parser("uninstall", help="stop and remove Kompactor from Claude Code settings")
+    p.add_argument("--purge", action="store_true", help="also delete ~/.kompactor (history and config)")
+    p.set_defaults(fn=cmd_uninstall)
+
     p = sp.add_parser("estimate", help="replay past Claude Code sessions and show %% Kompactor would save")
     p.add_argument("--root", help="transcripts dir (default ~/.claude/projects)")
     p.add_argument("--project", help="only this project folder under the root")
@@ -499,29 +510,12 @@ def main(argv=None):
     p = sp.add_parser("gain", help="live savings recorded by the hooks")
     p.set_defaults(fn=cmd_gain)
 
-    p = sp.add_parser("setup", help="one-step setup: enable for Claude Code (CLI + VS Code) and open the dashboard")
-    p.add_argument("--no-ui", action="store_true")
-    p.add_argument("--port", type=int, default=0)
-    p.set_defaults(fn=cmd_setup)
-
     p = sp.add_parser("ui", help="open the settings & savings dashboard (foreground; see `start`)")
     p.add_argument("--port", type=int, default=7420)
     p.add_argument("--no-browser", action="store_true")
     p.add_argument("--exact-port", action="store_true", help=argparse.SUPPRESS)
     p.set_defaults(fn=cmd_ui)
 
-    p = sp.add_parser("start", help="turn compaction on and run the dashboard in the background")
-    p.add_argument("--port", type=int, default=0, help="preferred port (default: any free port)")
-    p.add_argument("--no-browser", action="store_true")
-    p.set_defaults(fn=cmd_start)
-
-    p = sp.add_parser("stop", help="pause compaction and stop the background dashboard")
-    p.set_defaults(fn=cmd_stop)
-
-    p = sp.add_parser("uninstall", help="stop and remove Kompactor from Claude Code settings")
-    p.add_argument("--purge", action="store_true", help="also delete ~/.kompactor (history and config)")
-    p.set_defaults(fn=cmd_uninstall)
-
     p = sp.add_parser("install", help="add Kompactor hooks to Claude Code settings")
     p.add_argument("--project", action="store_true", help="write .claude/settings.json instead of ~/.claude")
     p.add_argument("--uninstall", action="store_true")

{kompactor-0.7.8 → kompactor-0.8.0}/kompactor/hooks.py

@@ -264,8 +264,9 @@ def pre_compact(event: dict, cfg: dict) -> None:
 
 
 def session_start(event: dict, cfg: dict) -> None:
-    try:  # so outputs can point at `~/.kompactor/bin/kompactor` even before `kompactor setup` (plugin installs)
+    try:  # so outputs can point at `~/.kompactor/bin/kompactor` even before `kompactor start` (plugin installs)
         installer.write_shim(only_if_changed=True)
+        installer.link_on_path()  # and so `kompactor` works in the user's own terminal too
     except OSError:
         pass
     if event.get("source") in ("compact", "clear"):

{kompactor-0.7.8 → kompactor-0.8.0}/kompactor/installer.py

@@ -64,6 +64,43 @@ def write_shim(only_if_changed: bool = False) -> Path:
             f.chmod(0o755)
     return d / "kompactor"
 
+
+# Where a `kompactor` command can be linked when pip put it in a folder that isn't on PATH.
+PATH_DIRS = ("~/.local/bin", "~/bin", "/opt/homebrew/bin", "/usr/local/bin")
+
+
+def link_on_path(path=None, dirs=None) -> str:
+    """Make `kompactor` work in any terminal. A pip install into a Python whose scripts folder isn't on
+    PATH leaves the command unreachable, so link the stable launcher into the first writable folder of
+    `dirs` that is already on PATH. Never edits shell files or replaces an existing command.
+    Returns the link it made, or ""."""
+    path = os.environ.get("PATH", "") if path is None else path
+    dirs = PATH_DIRS if dirs is None else dirs
+    if os.name == "nt" or shutil.which("kompactor", path=path):
+        return ""
+    on_path = {os.path.realpath(p) for p in path.split(os.pathsep) if p}
+    target = write_shim(only_if_changed=True)
+    for d in dirs:
+        d = os.path.expanduser(d)
+        link = Path(d, "kompactor")
+        if os.path.realpath(d) not in on_path or not os.access(d, os.W_OK) or link.exists() or link.is_symlink():
+            continue
+        try:
+            link.symlink_to(target)
+        except OSError:
+            continue
+        return str(link)
+    return ""
+
+
+def unlink_from_path(dirs=None) -> None:
+    """Remove the links link_on_path made, and only those."""
+    target = str(shim_dir() / "kompactor")
+    for d in PATH_DIRS if dirs is None else dirs:
+        link = Path(os.path.expanduser(d), "kompactor")
+        if link.is_symlink() and os.readlink(link) == target:
+            link.unlink()
+
 PREFIX_ENV = "CLAUDE_CODE_SHELL_PREFIX"
 # Claude Code runs every Bash command as `kompactor-shell '<command>'`. Only commands that look like
 # tests, builds, linters or installs start Python; the rest (and everything, if Kompactor is gone)
@@ -186,16 +223,16 @@ PLUGIN_SKILL = {"cmd": "~/.kompactor/bin/kompactor",
 
 SKILL = """---
 name: kompactor
-description: Kompactor token saver and code graph. Use when the user says /kompactor (setup, start, stop, uninstall, status, a level name, review, audit, debt, graph), asks about token savings, or when you need to find code by topic, see who uses something, or check what a change affects.
+description: Kompactor token saver and code graph. Use when the user says /kompactor (start, stop, uninstall, status, a level name, review, audit, debt, graph), asks about token savings, or when you need to find code by topic, see who uses something, or check what a change affects.
 ---
 
 Run these with Bash and report briefly. Kompactor token saver.{note}
 
 /kompactor status (or just /kompactor): run `{cmd} status` and summarise it in a few lines.
-/kompactor setup: run `{cmd} setup --no-ui` (adds the status line and the shell prefix that compacts failing commands, which a plugin can't set itself), report what it printed, and tell the user to restart Claude Code.
 Levels: `{cmd} presets`; change with `{cmd} config preset <N>` (1 Max quality, 2 Quality, 3 Balanced, 4 Savings, 5 Max savings; map words like "balanced" or "more savings").
-Savings: `{cmd} gain`. Dashboard: run `{cmd} start --no-browser` (returns at once, picks a free port) and give the user the URL it prints.
-/kompactor stop: `{cmd} stop` (pauses compaction, closes the dashboard). /kompactor start: `{cmd} start --no-browser`. /kompactor uninstall: `{cmd} uninstall`, then relay any extra command it prints.
+/kompactor start: run `{cmd} start --no-browser` (turns Kompactor on: hooks, status line and the shell prefix that compacts failing commands, plus the dashboard on a free port), give the user the dashboard URL it prints, and if it says so, tell them to restart Claude Code.
+/kompactor stop: `{cmd} stop` (pauses compaction, closes the dashboard). /kompactor uninstall: `{cmd} uninstall`, then relay any extra command it prints.
+Savings: `{cmd} gain`.
 
 Code graph (local, instant):
 - `{cmd} graph query "words"` find code by topic; `{cmd} graph explain Name` one symbol, its users and tests
@@ -270,6 +307,7 @@ def install(scope: str = "user", project: str = "", statusline: bool = True, uni
             pass
     skill = skill_path(scope, project)
     if uninstall:
+        unlink_from_path()
         if skill.exists() and "Kompactor token saver" in skill.read_text():
             skill.unlink()
             try:

{kompactor-0.7.8 → kompactor-0.8.0}/kompactor/prove.py

@@ -111,7 +111,7 @@ def run_once(task: dict, repo: Path, condition: str, work: Path, preset: int, mo
             settings.write_text(json.dumps(hook_settings()))
             args += ["--settings", str(settings)]
         tools += sorted({"Bash(kompactor:*)", f"Bash({installer.cli_name()}:*)"})
-        prefix = run_dir / "kompactor-shell"  # what `kompactor setup` installs as ~/.kompactor/bin/kompactor-shell
+        prefix = run_dir / "kompactor-shell"  # what `kompactor start` installs as ~/.kompactor/bin/kompactor-shell
         prefix.write_text(installer.SHELL_PREFIX.format(py=shlex.quote(sys.executable or "python3"),
                                                         script=shlex.quote(str(Path(installer.__file__).with_name("_launch.py")))))
         prefix.chmod(0o755)

{kompactor-0.7.8 → kompactor-0.8.0}/kompactor/static/usage.html

@@ -134,15 +134,15 @@ svg.chev { width: 11px; height: 11px; stroke: var(--ink-3); fill: none; stroke-w
         <div class="card"><b>Claude Code plugin</b><span class="muted">Recommended. Run these in any Claude Code session, one at a time. The last one adds the status line and the shell prefix, which a plugin can't set itself.</span>
           <pre><code>/plugin marketplace add <span data-repo>your-org/kompactor</span>
 /plugin install amarkum@kompactor
-/kompactor setup</code></pre></div>
+/kompactor start</code></pre></div>
         <div class="card"><b>pip / pipx / uv</b><span class="muted">macOS, Linux and Windows. Needs Python 3.9 or newer and nothing else.</span>
           <pre><code>pipx install kompactor
-kompactor setup</code></pre></div>
+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.7.8.vsix</code></pre></div>
+          <pre><code>code --install-extension kompactor-0.8.0.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>
+      <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>
       <p>Open the dashboard any time with <code>kompactor start</code> (it runs in the background; <code>kompactor stop</code> turns Kompactor off), or <b>Kompactor: Open Dashboard</b> in VS Code. Its <b>Setup</b> page shows these commands with your repo filled in, ready to copy.</p>
     </section>
 
@@ -152,8 +152,8 @@ kompactor setup</code></pre></div>
       <div class="tbl"><table>
         <tr><th>Way</th><th>Who it's for</th><th>What each person does</th><th>Updating</th></tr>
         <tr><td><b>Plugin</b></td><td>Everyone on Claude Code, CLI or VS Code</td><td>The three plugin commands under Install, once</td><td>Automatic with <code>autoUpdate</code> (below); or <code>claude plugin marketplace update kompactor</code>, then <code>claude plugin update amarkum@kompactor</code></td></tr>
-        <tr><td><b>Project settings</b></td><td>Everyone who works in a given repo</td><td>Trust the project folder when Claude Code asks, then <code>/kompactor setup</code> once; you commit the snippet below</td><td>Same as the plugin</td></tr>
-        <tr><td><b>pip / pipx / uv</b></td><td>People who manage Python tools that way</td><td><code>pipx install kompactor</code>, then <code>kompactor setup</code></td><td><code>pipx upgrade kompactor</code></td></tr>
+        <tr><td><b>Project settings</b></td><td>Everyone who works in a given repo</td><td>Trust the project folder when Claude Code asks, then <code>/kompactor start</code> once; you commit the snippet below</td><td>Same as the plugin</td></tr>
+        <tr><td><b>pip / pipx / uv</b></td><td>People who manage Python tools that way</td><td><code>pipx install kompactor</code>, then <code>kompactor start</code></td><td><code>pipx upgrade kompactor</code></td></tr>
         <tr><td><b>Terminal install</b></td><td>Scripted machine setup, or people who don't use plugins</td><td><code>git clone</code>, then <code>./kompactor/install.sh</code></td><td><code>git pull</code>, then run <code>./install.sh</code> again</td></tr>
         <tr><td><b>VS Code extension file</b></td><td>VS Code users who want the status bar and dashboard inside VS Code</td><td>Install the <code>.vsix</code> from Releases</td><td>Install the newer <code>.vsix</code></td></tr>
       </table></div>
@@ -165,7 +165,7 @@ kompactor setup</code></pre></div>
   },
   "enabledPlugins": { "amarkum@kompactor": true }
 }</code></pre>
-      <p class="muted">When a teammate opens the project and accepts Claude Code's prompt to trust the folder, Claude Code adds the marketplace and turns the plugin on. Each person then runs <code>/kompactor setup</code> once (plugins can't set the status line or the shell prefix themselves). <code>autoUpdate</code> keeps everyone on your latest release: teammates get a new version when <code>version</code> in <code>.claude-plugin/plugin.json</code> changes, and <code>python scripts/bump_version.py 0.4.1</code> bumps it everywhere.</p>
+      <p class="muted">When a teammate opens the project and accepts Claude Code's prompt to trust the folder, Claude Code adds the marketplace and turns the plugin on. Each person then runs <code>/kompactor start</code> once (plugins can't set the status line or the shell prefix themselves). <code>autoUpdate</code> keeps everyone on your latest release: teammates get a new version when <code>version</code> in <code>.claude-plugin/plugin.json</code> changes, and <code>python scripts/bump_version.py 0.4.1</code> bumps it everywhere.</p>
       <h3>Private-repo access</h3>
       <p>Claude Code uses each person's existing git login and can't prompt for a password. An SSH key that works with GitHub is enough. Without one, run <code>gh auth login</code> and <code>gh auth setup-git</code>, and set <code>CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1</code>.</p>
       <h3>Set the team's level for a repo</h3>

{kompactor-0.7.8 → kompactor-0.8.0}/kompactor/ui.html

@@ -722,9 +722,9 @@ function renderSetup() {
   const group = (label, ...codes) => `<div class="share-group"><div class="lbl">${label}</div>${codes.join("")}</div>`;
   const teamSettings = JSON.stringify({ extraKnownMarketplaces: { kompactor: { source: m.includes("://") ? { source: "git", url: clone } : { source: "github", repo: m }, autoUpdate: true } }, enabledPlugins: { "amarkum@kompactor": true } }, null, 2);
   $("snips").innerHTML =
-    group("Claude Code plugin: run these in any Claude Code session, one at a time", code(`/plugin marketplace add ${m}`), code("/plugin install amarkum@kompactor"), code("/kompactor setup")) +
-    group(`Everyone on a project: commit this as <span class="mono">.claude/settings.json</span>; Claude Code turns the plugin on once a teammate trusts the folder, then they run <span class="mono">/kompactor setup</span>`, code(teamSettings, true)) +
-    group("pip, pipx or uv (from PyPI)", code("pipx install kompactor"), code("kompactor setup")) +
+    group("Claude Code plugin: run these in any Claude Code session, one at a time", code(`/plugin marketplace add ${m}`), code("/plugin install amarkum@kompactor"), code("/kompactor start")) +
+    group(`Everyone on a project: commit this as <span class="mono">.claude/settings.json</span>; Claude Code turns the plugin on once a teammate trusts the folder, then they run <span class="mono">/kompactor start</span>`, code(teamSettings, true)) +
+    group("pip, pipx or uv (from PyPI)", code("pipx install kompactor"), code("kompactor start")) +
     group("Terminal (macOS, Linux), from a clone", code(`git clone ${clone} && ./${dir}/install.sh`)) +
     group(`VS Code: download the <span class="mono">.vsix</span> from the repo's GitHub Releases, then click Enable`, code(`code --install-extension kompactor-${S.version}.vsix`));
   $("snips").querySelectorAll("[data-copy]").forEach((b) => (b.onclick = async () => { try { await navigator.clipboard.writeText(b.dataset.copy); toast("Copied"); } catch (e) { toast("Select the text to copy it"); } }));

{kompactor-0.7.8 → kompactor-0.8.0}/kompactor.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kompactor
-Version: 0.7.8
+Version: 0.8.0
 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
@@ -112,17 +112,18 @@ Pick one. All of them set up the same thing, and the Claude Code CLI and VS Code
 ```
 /plugin marketplace add amarkum/kompactor
 /plugin install amarkum@kompactor
-/kompactor setup
+/kompactor start
 ```
-The last step adds the status line and the shell prefix that compacts failing commands, which a plugin can't set itself. Then restart Claude Code.
+The last step turns Kompactor on: it adds the status line and the shell prefix that compacts failing commands (a plugin can't set those itself) and opens the dashboard. Then restart Claude Code.
 
 **pip / pipx / uv** (macOS, Linux, Windows):
 ```bash
 pipx install kompactor        # or: pip install kompactor · uv tool install kompactor
-kompactor setup
+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.** Download `kompactor-0.7.8.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.8.0.vsix` from [Releases](https://github.com/amarkum/kompactor/releases), install it (Extensions › `⋯` › *Install from VSIX…*), and click **Enable** when Kompactor asks.
 
 **From source:**
 ```bash
@@ -135,12 +136,12 @@ 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.7.8: ON
+   Kompactor 0.8.0: 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`
    ```
-4. **Open the dashboard:** `kompactor start` runs it in the background on a free port and prints the address.
+4. **Three commands to remember:** `kompactor start` turns it on and opens the dashboard, `kompactor stop` pauses it, `kompactor uninstall` removes it.
 
 ## How it works
 
@@ -186,10 +187,10 @@ Ask Claude Code the way you normally would. These prompts come from the [evidenc
 
 | Command | What it does |
 |---|---|
+| `kompactor start` | Turn Kompactor on: connect it to Claude Code (CLI + VS Code) and open the dashboard on a free port |
+| `kompactor stop` | Pause it and close the dashboard; settings are kept |
+| `kompactor uninstall [--purge]` | Remove it from Claude Code (`--purge` also deletes `~/.kompactor`) |
 | `kompactor` / `kompactor status` | On or off, level, savings, how it works |
-| `kompactor setup` | Connect to Claude Code (CLI + VS Code) and open the dashboard |
-| `kompactor start` / `kompactor stop` | Turn on (dashboard in the background, free port) / pause |
-| `kompactor uninstall [--purge]` | Remove from Claude Code (`--purge` also deletes `~/.kompactor`) |
 | `kompactor presets` · `kompactor config preset 4` | List levels · change level |
 | `kompactor config <setting> <value>` | Change one [setting](#settings) |
 | `kompactor gain` | Savings so far |
@@ -224,7 +225,7 @@ Settings come from, in increasing priority: the level → your global choices
 | Setting | Type | What it does |
 |---|---|---|
 | `bash` | bool | Compact command output |
-| `bash_wrap` | bool | Compact failing commands too (needs the shell prefix from `kompactor setup`) |
+| `bash_wrap` | bool | Compact failing commands too (needs the shell prefix that `kompactor start` adds) |
 | `bash_plain` | bool | Ask Claude to run commands without `\| head`, `\| tail` or `\| grep`, since Kompactor keeps every failure |
 | `bash_min_tokens` | int | Leave outputs smaller than this untouched |
 | `bash_max_lines` | int | Max lines kept per output (head and tail kept; error lines from the middle always kept) |
@@ -306,7 +307,7 @@ kompactor graph unused                     dead-code candidates
   "enabledPlugins": { "amarkum@kompactor": true }
 }
 ```
-When a teammate trusts the folder, Claude Code installs the plugin; each person then runs `/kompactor setup` once. `autoUpdate` keeps everyone on the latest release. Admins can put the same keys in Claude Code's managed settings to roll it out to every machine, and a team that runs its own fork sets `KOMPACTOR_REPO` so the dashboard shows the fork's commands.
+When a teammate trusts the folder, Claude Code installs the plugin; each person then runs `/kompactor start` once. `autoUpdate` keeps everyone on the latest release. Admins can put the same keys in Claude Code's managed settings to roll it out to every machine, and a team that runs its own fork sets `KOMPACTOR_REPO` so the dashboard shows the fork's commands.
 
 ## Evidence
 
@@ -369,13 +370,13 @@ Command output from any language is compacted. These languages also get language
 
 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 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 start` 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).
 
 **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; 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. History is deleted after 30 days by default. 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 writes.** `~/.kompactor/`: settings, the savings ledger, raw copies of shortened output (for `kompactor show`), the code graph index and the `~/.kompactor/bin/` launchers. When `kompactor` isn't on your PATH, it adds one link to that launcher in a writable folder that already is (`~/.local/bin`, `~/bin`, `/opt/homebrew/bin` or `/usr/local/bin`); it never edits shell files or replaces an existing command, and `kompactor uninstall` removes the link. History is deleted after 30 days by default. `kompactor start` 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).
 
@@ -383,7 +384,8 @@ Everything below happens on your machine. Kompactor makes no network requests of
 
 | 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. |
+| `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 writable folder already on your PATH, such as `~/.local/bin`. Claude Code plugin installs do this at the first session. |
+| No savings line after replies | Restart Claude Code after `kompactor start`, 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>`, 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 to `never_compact` in `.kompactor.json`. 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`. |
@@ -455,5 +457,3 @@ Bug reports, ideas and pull requests are welcome. See [CONTRIBUTING.md](https://
 ## License
 
 [MIT](https://github.com/amarkum/kompactor/blob/main/LICENSE) © The Kompactor authors. The dashboard uses the IBM Plex fonts under the [SIL Open Font License](https://github.com/amarkum/kompactor/blob/main/kompactor/static/fonts/OFL.txt).
-
-Built by [stackcone](https://stackcone.com). Read the story behind it: [Kompactor: Cut the Tokens Claude Code Spends on Noise](https://stackcone.com/blog/posts/kompactor-claude-code-token-saver/).

{kompactor-0.7.8 → kompactor-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kompactor"
-version = "0.7.8"
+version = "0.8.0"
 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.8 → kompactor-0.8.0}/tests/test_graph.py

@@ -11,7 +11,8 @@ from pathlib import Path
 
 os.environ.setdefault("KOMPACTOR_HOME", tempfile.mkdtemp())
 
-from kompactor import config, graph, hooks  # noqa: E402
+from kompactor import config, graph, hooks, installer  # noqa: E402
+installer.PATH_DIRS = ()  # never link `kompactor` into real PATH folders from tests
 
 
 def make_repo(files: dict) -> str:

{kompactor-0.7.8 → kompactor-0.8.0}/tests/test_kompactor.py

@@ -12,6 +12,7 @@ TMP = tempfile.mkdtemp()
 os.environ["KOMPACTOR_HOME"] = os.path.join(TMP, "home")
 
 from kompactor import config, estimate, filters, hooks, installer, langs, outline, server, store, tokens  # noqa: E402
+installer.PATH_DIRS = ()  # never link `kompactor` into real PATH folders from tests
 
 
 def run_hook(name, event):
@@ -565,6 +566,24 @@ class SourceTests(unittest.TestCase):
         self.assertEqual(installer.parse_source(ssh)["clone"], ssh)
         self.assertEqual(installer.parse_source(""), {})
 
+    def test_command_linked_onto_path_when_missing(self):
+        from unittest import mock
+        tmp = Path(tempfile.mkdtemp())
+        on_path, off_path, shim = tmp / "bin", tmp / "elsewhere", tmp / "shim"
+        on_path.mkdir(); off_path.mkdir()
+        with mock.patch.object(installer, "shim_dir", return_value=shim):
+            # only a writable folder that is already on PATH gets the link
+            link = installer.link_on_path(path=str(on_path), dirs=(str(off_path), str(on_path)))
+            self.assertEqual(link, str(on_path / "kompactor"))
+            self.assertEqual(os.readlink(link), str(shim / "kompactor"))
+            self.assertEqual(installer.link_on_path(path=str(on_path), dirs=(str(on_path),)), "")  # already there
+            installer.unlink_from_path(dirs=(str(on_path),))
+            self.assertFalse(Path(link).is_symlink())
+            (on_path / "kompactor").write_text("someone else's")  # never replaced
+            self.assertEqual(installer.link_on_path(path=str(on_path), dirs=(str(on_path),)), "")
+            installer.unlink_from_path(dirs=(str(on_path),))
+            self.assertTrue((on_path / "kompactor").exists())
+
     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

{kompactor-0.7.8 → kompactor-0.8.0}/tests/test_shell.py

@@ -20,6 +20,7 @@ ROOT = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(ROOT))
 
 from kompactor import filters, hooks, installer, shellwrap, tokens  # noqa: E402
+installer.PATH_DIRS = ()  # never link `kompactor` into real PATH folders from tests
 
 PASSING = "".join(f"tests/test_mod.py::test_case_{i} PASSED{' ' * 30}[{i // 5:3d}%]\n" for i in range(500))
 FAILURE = ("=================================== FAILURES ===================================\n"