@tokmizer/plugin 0.9.56 → 0.9.58

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tokmizer",
-  "version": "0.9.56",
+  "version": "0.9.58",
   "description": "Tokmizer reduces token consumption for AI agents.",
   "author": {
     "name": "Tokmizer",

package/README.md

@@ -13,7 +13,7 @@ In Claude Code:
 /plugin install tokmizer@tokmizer
 ```
 
-Then restart Claude Code once, hooks only load at startup. Verify with `/tkr-status`, you should see your plan and Active.
+Then restart Claude Code once, hooks only load at startup. Verify with `/tkr-status`, you should see Status active.
 
 Any other tool (universal shell-shim):
 
@@ -38,6 +38,59 @@ tkr setup-codex
 
 Restart Codex, then approve the hook in `/hooks`.
 
+Cursor or Gemini CLI, after installing with npm or Homebrew:
+
+```bash
+tkr setup-cursor
+tkr setup-gemini
+```
+
+`tkr setup-cursor` adds a `preToolUse` hook to `~/.cursor/hooks.json`; `tkr setup-gemini` adds a `BeforeTool` hook to `~/.gemini/settings.json`. Each hook routes the agent's shell commands through Tokmizer before they run, keeps your other hooks and settings, and saves a `.tkr-bak` copy the first time it edits the file. Remove either with `--remove`. Cursor's `afterShellExecution` and Gemini's `AfterTool` events cannot replace command output, so these hooks rewrite the command itself.
+
+Other agents with plugin or hook support:
+
+| Agent | Command | What it installs |
+| --- | --- | --- |
+| OpenCode | `tkr setup-opencode` | plugin `~/.config/opencode/plugins/tokmizer.js` |
+| Kilo Code (CLI and VS Code extension) | `tkr setup-kilo` | plugin `~/.config/kilo/plugin/tokmizer.js` |
+| Amp | `tkr setup-amp` | plugin `~/.config/amp/plugins/tokmizer.js` |
+| Mistral Vibe | `tkr setup-vibe` | `pre_tool` hook in `~/.vibe/hooks.toml` |
+| Antigravity | `tkr setup-antigravity` | `PreToolUse` hook in `~/.gemini/config/hooks.json` |
+| OpenClaw | `tkr setup-openclaw` | plugin `~/.openclaw/extensions/tokmizer/`, then `openclaw plugins enable tokmizer` |
+| Pi | `tkr setup-pi` | extension `~/.pi/agent/extensions/tokmizer.js` |
+| Oh My Pi | `tkr setup-omp` | extension `~/.omp/agent/extensions/tokmizer.js` |
+| Hermes | `tkr setup-hermes` | plugin `~/.hermes/plugins/tokmizer/`, then `hermes plugins enable tokmizer` (Hermes v2026.8.16 or newer) |
+
+Each plugin asks `tkr rewrite` for the Tokmizer form of a shell command just before the agent runs it. If `tkr` is missing, slow or fails, the command runs as typed. `XDG_CONFIG_HOME`, `VIBE_HOME`, `PI_CODING_AGENT_DIR` and `HERMES_HOME` are respected. Run the same command with `--remove` to take it out; your other plugins, hooks and settings are kept.
+
+GitHub Copilot, Factory Droid, Trae, Qwen Code, Crush, Junie CLI, ZCode or Grok Build, after installing with npm or Homebrew:
+
+```bash
+tkr setup-copilot
+tkr setup-droid
+tkr setup-trae
+tkr setup-qwen
+tkr setup-crush
+tkr setup-junie
+tkr setup-zcode
+tkr setup-grok
+```
+
+| Command | Agent | File it edits |
+|---|---|---|
+| `tkr setup-copilot` | Copilot in VS Code and Copilot CLI | `~/.copilot/hooks/tokmizer.json` (or `$COPILOT_HOME/hooks/`) |
+| `tkr setup-droid` | Factory Droid | `~/.factory/hooks.json`, or `~/.factory/settings.json` when your own `PreToolUse` hooks live there |
+| `tkr setup-trae` | Trae | `~/.trae/hooks.json`, plus `~/.trae-cn/hooks.json` when Trae CN is installed |
+| `tkr setup-qwen` | Qwen Code | `~/.qwen/settings.json` (or `$QWEN_HOME`) |
+| `tkr setup-crush` | Crush | `~/.config/crush/crush.json` (or `$XDG_CONFIG_HOME/crush/`) |
+| `tkr setup-junie` | Junie CLI | `~/.junie/config.json` |
+| `tkr setup-zcode` | ZCode | `~/.zcode/cli/config.json` (`hooks.events.PreToolUse`) |
+| `tkr setup-grok` | Grok Build 1.0.4 or newer | `~/.grok/hooks/tokmizer.json` |
+
+Each command adds one `PreToolUse` hook for the agent's shell tool. It rewrites the command before it runs, never approves it: the agent keeps asking for permission as usual. Your other hooks and settings stay as they are, a `.tkr-bak` copy is saved the first time a file is edited, and `--remove` takes the hook out again. Restart the agent after setup. Crush still reads `crush.json` but now prefers `crushrc`; a `crush.json` with comments is left untouched and reported.
+
+Permission rules stay in force. Agents match their allow, ask and deny rules against the command text, so Tokmizer leaves a command untouched whenever one of your deny or ask rules matches it. Tokmizer reads those rules for Claude Code (`permissions.deny` and `permissions.ask` in user, project, local and managed settings), OpenCode (`permission` in `opencode.json`), Cursor CLI (`permissions.deny`), Gemini CLI (policy files and `tools.exclude`) and Antigravity CLI (`permissions.deny` and `permissions.ask`). For the other agents, and on top of the Cursor, Gemini and Antigravity rules, only inspection, build and test commands (`cat`, `rg`, `git log`, `npm test`, `cargo build` and similar; inspection only for Codex) are routed; anything else, such as `git push` or `rm`, runs exactly as typed. If a settings file cannot be read, nothing is routed.
+
 Homebrew:
 
 ```bash
@@ -63,16 +116,16 @@ In Claude Code:
 - `/tkr-link tokmizer_yourkey` connects an optional account
 - `/tkr-unlink` unlinks this machine from your account
 - `/tkr-gain` shows the estimated reduction in command-output tokens
-- `/tkr-status` shows your current plan and usage
+- `/tkr-status` shows your account and engine status
 - `/tkr-compression` picks the compression level (light, balanced, max)
 - `/tkr-yolo on` explicitly enables YOLO on this machine; `/tkr-yolo off` disables it
 - `/tkr-reducer` makes the assistant's replies shorter (off, light, balanced, max)
-- `/tkr-telemetry` views or changes anonymous telemetry
+- `/tkr-telemetry` views or changes usage stats (command names and token counts; on by default, off in one command)
 - `/tkr-update` updates the plugin when a new version is out
 
 From any terminal (after the shell-shim install, or `npm install -g @tokmizer/plugin`):
 
-- `tkr status` shows your current plan and status
+- `tkr status` shows your account and engine status
 - `tkr gain` shows the estimated reduction in command-output tokens
 - `tkr link <key>` connects an optional account
 - `tkr unlink` unlinks this machine
@@ -80,6 +133,8 @@ From any terminal (after the shell-shim install, or `npm install -g @tokmizer/pl
 - `tkr yolo on|off|status` enables, disables, or checks the local YOLO mode
 - `tkr reducer off|light|balanced|max` makes the assistant's replies shorter (default off)
 - `tkr settings show|set|configure` manages settings and syncs them across your machines
+- `tkr network off|on|status` blocks or allows every connection to tokmizer.com
+- `tkr migrate rtk` moves your rtk filters, settings and history over and turns off rtk hooks where Tokmizer runs (see [Switching from rtk to Tokmizer](#switching-from-rtk-to-tokmizer))
 
 ## Choosing a compression mode
 
@@ -112,8 +167,24 @@ Terminal commands managed by Tokmizer use the mode selected when execution start
 
 In the next release, successful `tkr restore` calls are counted as additional output in the local gain history, even with telemetry disabled. They reduce the net saving; repeated restorations count again and can make it negative. The display shows restored tokens separately. `gain --json` exposes the net estimate in `observed.savedTokens` and restoration totals in `restoration`; the existing top-level `savedTokens` remains the total for reduced outputs only. Earlier restorations cannot be reconstructed from local history. Manually repeated commands, prompts, replies and replayed conversation context are not attributed to restoration costs.
 
+Other local views: `tkr gain --by-rule` groups savings by rule (your custom filters by name, built-in rules by command), `tkr gain --failures` lists commands whose output went through unchanged and why (no rule, nothing to cut, failed run kept in full), and `tkr gain --quota [pro|5x|20x]` estimates the share of a Claude plan budget the savings represent. The quota view is an estimate, not a plan limit: tokens saved per day × 30, divided by an assumed 44,000 tokens per 5-hour window × 144 windows × the plan multiplier (1, 5 or 20). Anthropic does not publish plan limits in tokens. All three combine with a period, `--project` and `--json`.
+
 The percentages in `tkr gain` measure byte reduction. A byte percentage can differ substantially from the reduction counted by a model's tokenizer. Restoring a full file after reading its outline can cost more tokens than reading it once. Compression is not a promise of faster task completion or a correct answer.
 
+## Restoring shortened output
+
+When Tokmizer shortens an output it can add a `[tkr restore <hash>]` hint. `tkr restore <hash>` prints the complete original output when it is at most 8 MB; for a larger output, the entry holds only the part that was left out and `tkr restore` says so. A unique prefix of the hash is enough.
+
+| Command | Effect |
+| --- | --- |
+| `tkr restore <hash>` | Print the cached output |
+| `tkr restore <hash> --lines 120:180` | Print only lines 120 to 180 (`120:`, `:40` and `57` also work) |
+| `tkr restore <hash> --grep <pattern>` | Print matching lines with their line numbers |
+| `tkr restore --grep <pattern>` | Search every cached output |
+| `tkr restore --list` | List cached outputs with age, size, line count and command |
+
+Entries are kept 30 days, up to 8 MB each and 200 MB in total; the oldest go first. `TOKMIZER_CCR_MAX_AGE_MS`, `TOKMIZER_CCR_ENTRY_MAX_BYTES` and `TOKMIZER_CCR_DIR_CAP_BYTES` change these limits, `TOKMIZER_CCR_DISABLED=1` turns copies off. `tkr gain` shows the restored tokens and the cache size.
+
 ## Measured comparison
 
 On October 9, 2026, a fixed set of 30 real and synthetic command outputs contained 774,863 tokens before compression. The table counts tokens with the cl100k tokenizer, excluding restoration notices. It is a test corpus, not a sample of customer usage.
@@ -137,6 +208,51 @@ In a separate controlled test for 0.9.52, a repetitive failure log went from 1,0
 
 These tokenizer counts are separate from the byte-based estimates in `tkr gain`. They measure output volume, not your bill, an agent's task success, or execution speed. See the [mode guide](https://tokmizer.com/en/docs#configuration) for usage and limits.
 
+## Custom filters
+
+Add your own output rules as `*.toml` files in `~/.tokmizer/filters/` (or `$TOKMIZER_HOME/filters/`). They load next to the built-in rules and win over them for the commands they match. They stay on your machine and are never uploaded. A file or rule that fails validation is skipped; `tkr doctor` shows what was loaded and why something was skipped.
+
+A file is used only after you trust it: review it, then run `tkr filters trust` (all files) or `tkr filters trust <file>`. Tokmizer records the file's SHA-256; editing the file stops it from being used until you trust it again. `tkr filters untrust [file]` removes the trust.
+
+```toml
+schema_version = 1
+
+[filters.make-check]
+match_command = "^make\\s+check(\\s|$)"
+strip_lines_matching = ["^make\\[\\d+\\]: (Entering|Leaving) directory"]
+max_lines = 120
+on_empty = "make check: no output"
+
+[[filters.make-check.tests]]
+name = "drops directory noise"
+input = "make[1]: Entering directory '/src'\nok\n"
+expected = "ok"
+```
+
+`schema_version` is optional; a version this tkr cannot read makes the file skipped with a message. `tkr filters test [rule]` runs the inline tests, including on files you have not trusted yet, and exits with 1 when one fails. Tests check the rule as written (the Light level) and ignore trailing whitespace; Balanced and Max shorten `max_lines` further.
+
+`match_command` is a regular expression tested against the command line. `strip_lines_matching` drops matching lines, `max_lines` caps the number of lines kept and `on_empty` replaces an empty result. Also available: `strip_ansi = true`, `keep_failures = true` (failure lines survive the cap), `truncate_lines_at = 400`, and `priority = 60` to pick between several of your rules that match the same command.
+
+## Switching from rtk to Tokmizer
+
+If you already use rtk, one command brings over what can be brought over and stops commands from going through two hooks:
+
+```sh
+tkr migrate rtk            # show the plan, then ask before changing anything
+tkr migrate rtk --dry-run  # only show the plan
+tkr migrate rtk --yes      # apply without asking
+tkr migrate rtk --undo     # put back every file the migrations changed, newest first
+```
+
+- **Filters.** rtk's global `filters.toml` (`~/.config/rtk/` on Linux, `~/Library/Application Support/rtk/` on macOS, `%APPDATA%\rtk\` on Windows) and the project's `.rtk/filters.toml` become files in `~/.tokmizer/filters/`. Their `[[tests]]` run again on Tokmizer and each result is printed. A filter that uses an option Tokmizer filters do not have (`replace`, `match_output`, `keep_lines_matching`, `head_lines`, `tail_lines`, `filter_stderr`) is not imported, and the plan says why. A file rtk had trusted stays trusted; the others, and project files (Tokmizer filters apply in every project), wait for `tkr filters trust`.
+- **Settings.** From `config.toml`: `exclude_commands` (the output of those commands is left unchanged), the `rtk recall` retention or its `disabled` mode (`~/.tokmizer/restore.json`), and telemetry turned off (`tkr telemetry off`). Every other setting is listed as not imported.
+- **History.** The totals in rtk's `history.db` are read without changing it. `tkr gain` shows them on their own "Imported from rtk" line, never added to the savings Tokmizer measured. An unreadable file is skipped.
+- **Agent hooks.** For each agent where both rtk and Tokmizer are installed (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Factory Droid, Trae, Mistral Vibe, Antigravity, OpenCode, Pi, Oh My Pi), the rtk hook is removed so commands are not wrapped twice. Where Tokmizer is not installed yet, the rtk hook stays and the plan says which `tkr setup-…` to run first. rtk's own proxy setting (`ANTHROPIC_BASE_URL`) is left alone. `tkr doctor` reports any agent where both still hook the same commands.
+
+Every changed file is backed up under `~/.tokmizer/migrate-rtk/`. Running `--yes` again changes only what is new since the last migration and says `Already migrated` when nothing is; `--undo` reverts every migration still in place, newest first, and does not overwrite a file you changed after the migration: it tells you where its backup is.
+
+`tkr migrate rtk --shim` also adds an `rtk` command to `~/.tokmizer/shims` for scripts and habits: `rtk gain` runs `tkr gain`, `rtk recall <hash>` runs `tkr restore <hash>`, `rtk bypass <cmd>` (or `rtk proxy <cmd>`) runs the command unchanged, and any other subcommand explains what to run instead. It takes over once rtk itself is uninstalled and `~/.tokmizer/shims` is on your `PATH`.
+
 ## Distribution
 
 This README is shared by the npm package and the public GitHub repository.
@@ -146,12 +262,55 @@ This README is shared by the npm package and the public GitHub repository.
 
 The optimization engine and API client ship compiled with [`@tokmizer/plugin`](https://www.npmjs.com/package/@tokmizer/plugin). Their source code is not in the public repository.
 
-## Privacy
+## Network & privacy
+
+Tokmizer works without an account or email. It contacts `tokmizer.com` to keep its rules up to date and to improve the product. One command turns all of it off: `tkr network off`.
+
+What leaves your machine, and when:
+
+| When | What is sent | Why |
+|---|---|---|
+| First online run, no account | A random install ID, your computer name, OS and version, CPU model and core count, a SHA-256 hash of your network card (MAC) address, a SHA-256 hash of your user name, a fingerprint (SHA-256 of all of these), your time zone and the plugin version | Create the install token used to download rules |
+| `tkr link <key>` | The same, plus your key, and your email only if you pass `--email` | Attach this machine to your account |
+| Regular check-in (heartbeat) | Install ID, fingerprint, plugin version, local date and time zone | Refresh access and learn that a new version is out |
+| Rule downloads | Install ID, fingerprint, plugin version | Get the latest compression rules and the `/power` and reducer instructions |
+| Settings sync, linked accounts only | Your Tokmizer settings | Keep them in sync with the dashboard |
+| Usage stats, only while they are on (with or without an account) | Command names such as `npm install` (never arguments; Git and GitHub commands excluded), token counts, rule IDs with output sizes, session ID, agent name | See which commands to optimize next |
+| `tkr unlink` | Install ID, fingerprint | Remove this device from your account |
+| CLI self-update, after a check-in reports a new version | Runs `npm i -g @tokmizer/plugin@<version>` or `brew upgrade tokmizer`, which contact the npm registry, Homebrew and GitHub | Keep the CLI current (`tkr auto-update off` stops only this) |
+
+The hashes are not anonymous: the same machine always gives the same values, and a user name hash can be guessed. Like any web server, `tokmizer.com` sees your IP address and keeps it in its security log. Tokmizer never sends command arguments, command output, file contents or file paths.
+
+Usage stats are on by default and off in one command: `tkr telemetry off` (or `tkr network off` to stop every connection). The choice is saved on this machine and survives updates; an install that turned them off stays off. Before anything is sent, Tokmizer says so once, in the terminal or in the Claude Code session notice. Check with `tkr telemetry status`.
+
+### Usage stats without an account
+
+Usage stats do not need an account. Without one, they are stored against this install's random key, not against an email or a person. They are still not anonymous: the computer name and the other device details listed above are sent when the install registers and are kept with that key.
+
+- **Sent:** for each command, its name, the token count before compression, tokens saved and restored, whether it was compressed, the session ID and the agent name. Never arguments, output, file contents or paths.
+- **Only with your consent:** the plugin uploads them only while `tkr telemetry status` says `on`, and tells the server so with each upload. Nothing is accepted from an install that is off or whose network is off.
+- **Once per install, before the first upload:** Tokmizer says so once (first run, setup, session start or upgrade) and sends nothing until that notice has been shown, then stays quiet.
+- **Kept:** detailed rows for 90 days, then only a running total of tokens saved per key.
+- **Linking later:** `tkr link` moves the install's past usage stats to your account, so your dashboard includes them.
+- **Turn off:** `tkr telemetry off`. To stop every connection: `tkr network off`.
+
+### Turn the network off
+
+```bash
+tkr network off      # nothing leaves this machine
+tkr network status
+tkr network on
+```
+
+In CI or for one shell, set `TOKMIZER_NETWORK=0`. `tkr status` and `tkr doctor` show the current state.
+
+While it is off there is no sign-up, heartbeat, rule download, settings sync, usage stats or update check. Tokmizer keeps compressing locally: with the last downloaded rules for up to 7 days, then with its core built-in rules. Settings are saved on this machine only. `tkr link` and `tkr heartbeat` explain how to turn the network back on.
+
+The switch does not cover Claude Code's own marketplace auto-update, which `/tkr-update` turns on (set `extraKnownMarketplaces.tokmizer.autoUpdate` to `false` in `~/.claude/settings.json` to stop it), nor commands you run yourself such as the installer, `/tkr-update`, npm or brew.
+
+### Local data
 
-- When telemetry is enabled, Tokmizer reports command names, usage counters, and session metadata, without your source code, arguments, or command output. Turn it off with `tkr telemetry off`.
-- In 0.9.52, telemetry defaults to on unless setup or saved settings turn it off. Check `tkr telemetry status`; using Tokmizer without an account does not itself disable telemetry.
-- Turning telemetry off stops optional usage reporting. Initial activation, rule downloads, update checks and account synchronization are separate network operations. Activation includes device and installation metadata. Offline use requires previously downloaded rules and is subject to cache availability and expiry.
-- Restoration copies are local and temporary. A restore hint identifies available cached content; there is no guarantee that every removed detail has a saved copy. YOLO creates no new restoration copies.
+- Restoration copies are local and kept up to 30 days. A restore hint identifies available cached content; there is no guarantee that every removed detail has a saved copy. YOLO creates no new restoration copies.
 - The public [redaction helpers](https://github.com/norwelltw/Tokmizer/blob/main/src/learn/redact.ts) are available for inspection.
 - Local state lives in `~/.tokmizer/`.
 

package/agent-plugins/amp.js

@@ -0,0 +1,38 @@
+import { execFile } from "node:child_process";
+
+const TKR = __TKR_ARGV__;
+const ARGS = ["rewrite", "--host", "amp"];
+
+export const description = "Routes shell commands through tokmizer to cut tool-output tokens.";
+
+function rewrite(command, session) {
+  return new Promise((resolve) => {
+    if (typeof command !== "string" || !command.trim()) return resolve(null);
+    try {
+      const args = [...TKR.slice(1), ...ARGS, ...(typeof session === "string" && session ? ["--session", session] : [])];
+      const child = execFile(TKR[0], args, { timeout: 3000, windowsHide: true, encoding: "utf8", maxBuffer: 1 << 20 }, (error, stdout) => {
+        resolve(!error && typeof stdout === "string" && stdout.trim() ? stdout : null);
+      });
+      child.stdin?.on("error", () => {});
+      child.stdin?.end(command);
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+export default function (amp) {
+  amp.on("tool.call", async (event) => {
+    try {
+      const shell = amp.helpers?.shellCommandFromToolCall?.(event);
+      const input = event?.input;
+      if (!shell || !input || typeof input !== "object") return { action: "allow" };
+      const key = input.command === shell.command ? "command" : input.cmd === shell.command ? "cmd" : null;
+      if (!key) return { action: "allow" };
+      const rewritten = await rewrite(shell.command, event?.thread?.id);
+      return rewritten ? { action: "modify", input: { ...input, [key]: rewritten } } : { action: "allow" };
+    } catch {
+      return { action: "allow" };
+    }
+  });
+}

package/agent-plugins/hermes/__init__.py

@@ -0,0 +1,39 @@
+import subprocess
+
+TKR = __TKR_ARGV__
+ARGS = ["rewrite", "--host", "hermes"]
+
+
+def _rewrite(command, session):
+    extra = ["--session", session] if isinstance(session, str) and session else []
+    result = subprocess.run(
+        TKR + ARGS + extra,
+        input=command,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        timeout=3,
+        shell=False,
+    )
+    if result.returncode != 0 or not result.stdout.strip():
+        return None
+    return result.stdout
+
+
+def _pre_tool_call(tool_name=None, args=None, **kwargs):
+    try:
+        if tool_name != "terminal" or not isinstance(args, dict):
+            return None
+        command = args.get("command")
+        if not isinstance(command, str) or not command.strip():
+            return None
+        rewritten = _rewrite(command, kwargs.get("session_id"))
+        if not rewritten:
+            return None
+        return {"action": "modify", "args": {"command": rewritten}}
+    except Exception:
+        return None
+
+
+def register(ctx):
+    ctx.register_hook("pre_tool_call", _pre_tool_call)

package/agent-plugins/hermes/plugin.yaml

@@ -0,0 +1,5 @@
+name: tokmizer
+version: "1.0"
+description: Routes terminal commands through tokmizer to cut tool-output tokens.
+provides_hooks:
+  - pre_tool_call

package/agent-plugins/kilo.js

@@ -0,0 +1,40 @@
+import { execFile } from "node:child_process";
+
+const TKR = __TKR_ARGV__;
+const ARGS = ["rewrite", "--host", "kilo"];
+
+function rewrite(command, session) {
+  return new Promise((resolve) => {
+    if (typeof command !== "string" || !command.trim()) return resolve(null);
+    try {
+      const args = [...TKR.slice(1), ...ARGS, ...(typeof session === "string" && session ? ["--session", session] : [])];
+      const child = execFile(TKR[0], args, { timeout: 3000, windowsHide: true, encoding: "utf8", maxBuffer: 1 << 20 }, (error, stdout) => {
+        resolve(!error && typeof stdout === "string" && stdout.trim() ? stdout : null);
+      });
+      child.stdin?.on("error", () => {});
+      child.stdin?.end(command);
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+async function apply(tool, container, session) {
+  try {
+    if ((tool !== "bash" && tool !== "shell") || !container || typeof container !== "object") return;
+    const rewritten = await rewrite(container.command, session);
+    if (rewritten) container.command = rewritten;
+  } catch {}
+}
+
+export default {
+  id: "tokmizer",
+  async setup(ctx) {
+    await ctx?.tool?.hook?.("execute.before", (event) => apply(event?.tool, event?.input, event?.sessionID));
+  },
+  async server() {
+    return {
+      "tool.execute.before": (input, output) => apply(input?.tool, output?.args, input?.sessionID)
+    };
+  }
+};

package/agent-plugins/omp.js

@@ -0,0 +1,32 @@
+import { execFile } from "node:child_process";
+
+const TKR = __TKR_ARGV__;
+const ARGS = ["rewrite", "--host", "omp"];
+
+function rewrite(command, session) {
+  return new Promise((resolve) => {
+    if (typeof command !== "string" || !command.trim()) return resolve(null);
+    try {
+      const args = [...TKR.slice(1), ...ARGS, ...(typeof session === "string" && session ? ["--session", session] : [])];
+      const child = execFile(TKR[0], args, { timeout: 3000, windowsHide: true, encoding: "utf8", maxBuffer: 1 << 20 }, (error, stdout) => {
+        resolve(!error && typeof stdout === "string" && stdout.trim() ? stdout : null);
+      });
+      child.stdin?.on("error", () => {});
+      child.stdin?.end(command);
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+export default function (pi) {
+  pi.on("tool_call", async (event) => {
+    try {
+      if (event?.toolName !== "bash" || !event.input || typeof event.input !== "object") return;
+      const rewritten = await rewrite(event.input.command);
+      return rewritten ? { input: { ...event.input, command: rewritten } } : undefined;
+    } catch {
+      return undefined;
+    }
+  });
+}

package/agent-plugins/openclaw/index.js

@@ -0,0 +1,39 @@
+import { execFile } from "node:child_process";
+
+const TKR = __TKR_ARGV__;
+const ARGS = ["rewrite", "--host", "openclaw"];
+
+function rewrite(command, session) {
+  return new Promise((resolve) => {
+    if (typeof command !== "string" || !command.trim()) return resolve(null);
+    try {
+      const args = [...TKR.slice(1), ...ARGS, ...(typeof session === "string" && session ? ["--session", session] : [])];
+      const child = execFile(TKR[0], args, { timeout: 3000, windowsHide: true, encoding: "utf8", maxBuffer: 1 << 20 }, (error, stdout) => {
+        resolve(!error && typeof stdout === "string" && stdout.trim() ? stdout : null);
+      });
+      child.stdin?.on("error", () => {});
+      child.stdin?.end(command);
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+export default {
+  id: "tokmizer",
+  name: "Tokmizer",
+  description: "Routes exec commands through tokmizer to cut tool-output tokens.",
+  register(api) {
+    api.on("before_tool_call", async (event) => {
+      try {
+        if (event?.toolName !== "exec" || event.toolKind === "code_mode_exec") return undefined;
+        const params = event.params;
+        if (!params || typeof params !== "object") return undefined;
+        const rewritten = await rewrite(params.command);
+        return rewritten ? { params: { ...params, command: rewritten } } : undefined;
+      } catch {
+        return undefined;
+      }
+    });
+  }
+};

package/agent-plugins/openclaw/openclaw.plugin.json

@@ -0,0 +1,12 @@
+{
+  "id": "tokmizer",
+  "name": "Tokmizer",
+  "description": "Routes exec commands through tokmizer to cut tool-output tokens.",
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false
+  }
+}

package/agent-plugins/openclaw/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "tokmizer-openclaw",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ]
+  }
+}

package/agent-plugins/opencode.js

@@ -0,0 +1,40 @@
+import { execFile } from "node:child_process";
+
+const TKR = __TKR_ARGV__;
+const ARGS = ["rewrite", "--host", "opencode"];
+
+function rewrite(command, session) {
+  return new Promise((resolve) => {
+    if (typeof command !== "string" || !command.trim()) return resolve(null);
+    try {
+      const args = [...TKR.slice(1), ...ARGS, ...(typeof session === "string" && session ? ["--session", session] : [])];
+      const child = execFile(TKR[0], args, { timeout: 3000, windowsHide: true, encoding: "utf8", maxBuffer: 1 << 20 }, (error, stdout) => {
+        resolve(!error && typeof stdout === "string" && stdout.trim() ? stdout : null);
+      });
+      child.stdin?.on("error", () => {});
+      child.stdin?.end(command);
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+async function apply(tool, container, session) {
+  try {
+    if ((tool !== "bash" && tool !== "shell") || !container || typeof container !== "object") return;
+    const rewritten = await rewrite(container.command, session);
+    if (rewritten) container.command = rewritten;
+  } catch {}
+}
+
+export default {
+  id: "tokmizer",
+  async setup(ctx) {
+    await ctx?.tool?.hook?.("execute.before", (event) => apply(event?.tool, event?.input, event?.sessionID));
+  },
+  async server() {
+    return {
+      "tool.execute.before": (input, output) => apply(input?.tool, output?.args, input?.sessionID)
+    };
+  }
+};

package/agent-plugins/pi.js

@@ -0,0 +1,30 @@
+import { execFile } from "node:child_process";
+
+const TKR = __TKR_ARGV__;
+const ARGS = ["rewrite", "--host", "pi"];
+
+function rewrite(command, session) {
+  return new Promise((resolve) => {
+    if (typeof command !== "string" || !command.trim()) return resolve(null);
+    try {
+      const args = [...TKR.slice(1), ...ARGS, ...(typeof session === "string" && session ? ["--session", session] : [])];
+      const child = execFile(TKR[0], args, { timeout: 3000, windowsHide: true, encoding: "utf8", maxBuffer: 1 << 20 }, (error, stdout) => {
+        resolve(!error && typeof stdout === "string" && stdout.trim() ? stdout : null);
+      });
+      child.stdin?.on("error", () => {});
+      child.stdin?.end(command);
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+export default function (pi) {
+  pi.on("tool_call", async (event) => {
+    try {
+      if (event?.toolName !== "bash" || !event.input || typeof event.input !== "object") return;
+      const rewritten = await rewrite(event.input.command);
+      if (rewritten) event.input.command = rewritten;
+    } catch {}
+  });
+}

package/codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tokmizer",
-  "version": "0.9.56",
+  "version": "0.9.58",
   "description": "Tokmizer reduces token consumption for OpenAI Codex.",
   "author": "Tokmizer",
   "homepage": "https://tokmizer.com"

package/command-templates/tkr-gain.md

@@ -1,6 +1,6 @@
 ---
 description: Show estimated token reductions in recorded tool outputs.
-argument-hint: [--day | --week | --month]
+argument-hint: [--day | --week | --month] [--project [path]] [--csv | --graph | --history | --by-rule | --failures | --quota [pro|5x|20x]]
 ---
 
 Show the user Tokmizer's recorded tool-output reductions.
@@ -17,11 +17,16 @@ Choose the scope the user requested:
 - Today or `--day`: `gain --day` for the current local calendar day.
 - Last seven days or `--week`: `gain --week`.
 - Last thirty days or `--month`: `gain --month`.
+- Only this project (or a given directory): add `--project` or `--project <path>`. It covers the live local journal only; older rotated history is not included, and commands recorded before this field existed are excluded.
+- Export or alternative views, combinable with a period: `--csv` (one row per day), `--graph` (per-day bar chart, default last 30 days), `--history` (last 20 recorded commands).
+- Savings per rule: `--by-rule` (custom filters by name, built-in rules grouped by command).
+- Commands left unchanged and why: `--failures`.
+- Share of a Claude plan budget: `--quota`, optionally followed by `pro`, `5x` or `20x` (default `pro`, last 30 days unless a period is given). Only when the user asks for it; it is a labelled estimate with its formula, not a plan limit.
 - This session: `session` for session coverage. This command reports routing counts, not token or dollar savings.
 
 Show the CLI output verbatim inside a fenced code block: do not summarize, translate, reformat or rebuild it as a table. After the block, add at most one short sentence. Keep its measurement scope and caveats. Token counts are estimates from output bytes, not model tokenizer counts. Dollar values use reference input prices and do not measure a bill reduction. Percentages apply only to the recorded tool outputs, not all tokens used by the agent.
 
-Keep modeled reducer estimates separate from observed output reductions. Do not add them together, invent replay or repeated-context savings, or infer avoided model calls. Do not turn a period's estimate into a monthly projection or paid-plan payback. A comparison with another optimizer requires measurements on the same workload; these local totals alone do not establish one.
+Keep modeled reducer estimates separate from observed output reductions. Do not add them together, invent replay or repeated-context savings, or infer avoided model calls. Do not turn a period's estimate into a monthly projection or paid-plan payback, except the projection printed by `--quota`, kept with its estimate label. A comparison with another optimizer requires measurements on the same workload; these local totals alone do not establish one.
 
 If the output shows zero activity, report that no activity was recorded in the selected scope. This does not establish whether the optimizer is configured or running.
 

package/command-templates/tkr-link.md

@@ -11,7 +11,7 @@ If $ARGUMENTS contains a value starting with `tokmizer_`, run it immediately, no
 node "${CLAUDE_PLUGIN_ROOT}/dist/bin/tkr.js" link <that value>
 ```
 
-On success the command prints the active plan. Tell the user it is done.
+On success the command prints "Linked.". Tell the user it is done.
 
 If $ARGUMENTS contains no `tokmizer_...` value, do not run anything and reply exactly:
 

package/command-templates/tkr-status.md

@@ -1,5 +1,5 @@
 ---
-description: Show your Tokmizer plan, token state and features.
+description: Show your Tokmizer account and engine status.
 ---
 
 Show the user their Tokmizer account status.
@@ -10,8 +10,10 @@ Run the bundled CLI:
 node "${CLAUDE_PLUGIN_ROOT}/dist/bin/tkr.js" status
 ```
 
-Print the output as is. It includes the plan, the token state and whether `/power` is available right now.
+Print the output as is. It includes the network state, the token state, whether the device is linked and whether `/power` is available right now. Tokmizer is free: there is no plan or subscription to mention.
 
-If the user is on the free plan and asks how to upgrade, point them to https://tokmizer.com/#pricing and the `/tkr-link` command.
+If the user asks what Tokmizer sends over the network, answer plainly. No account or email is needed. Tokmizer contacts tokmizer.com to keep its rules up to date and to improve the product. It sends a random install ID, the computer name, OS and CPU model, a hash of the network card address and of the user name, and the plugin version. This is not anonymous: the same machine always gives the same values. Command contents and output are never sent. Usage stats (command names and token counts) are sent only if the user turned them on.
+
+If the output shows `Network: off`, explain that nothing leaves the machine and Tokmizer keeps compressing with the rules already on it. To turn it back on: `tkr network on`. To turn everything off: `tkr network off`; usage stats only: `tkr telemetry off`.
 
 If the command fails because the plugin files are missing, tokmizer was uninstalled. Offer to clean up: delete the tokmizer-managed `tkr*.md` copies (they end with a `managed-by: tokmizer` marker) from `~/.claude/commands/`.

package/command-templates/tkr-telemetry.md

@@ -1,5 +1,5 @@
 ---
-description: Show or change Tokmizer anonymous telemetry (status, on, off, forget).
+description: Show or change Tokmizer usage stats (status, on, off, forget).
 argument-hint: status | on | off | forget
 ---
 
@@ -11,11 +11,11 @@ Pick the subcommand from the user's request. Default to `status` when they only
 node "${CLAUDE_PLUGIN_ROOT}/dist/bin/tkr.js" telemetry status
 ```
 
-- `telemetry status` shows whether anonymous telemetry is on or off and the local record count.
+- `telemetry status` shows whether usage stats are on or off, the network state, whether an account is linked, what is sent and the local record count.
 - `telemetry on` turns it on.
 - `telemetry off` turns it off.
 - `telemetry forget` erases telemetry data stored on this machine.
 
-Print the output as is. If the user asks what is collected, tell them: anonymous command names and token savings only, never command contents, and the online dashboard at https://tokmizer.com needs telemetry on to show savings.
+Print the output as is. If the user asks what is collected, tell them: command names and token counts only, never arguments, output or file contents. Like every request to tokmizer.com, they come with the install ID and a fingerprint of the machine, so they are not anonymous. They are sent with or without an account; without one they are tied to the install's key, and linking an account later moves them to it. Detailed rows are kept 90 days. The online dashboard at https://tokmizer.com needs telemetry on to show savings. To stop every connection, not only usage stats, the user runs `tkr network off`.
 
 If the command fails because the plugin files are missing, tokmizer was uninstalled. Offer to clean up: delete the tokmizer-managed `tkr*.md` copies (they end with a `managed-by: tokmizer` marker) from `~/.claude/commands/`.