/token-saver-config

name: token-saver-config
description: "Configure and diagnose token-saver compression settings. Use when the user asks about adjusting compression levels, checking processor status, debugging hook issues, or reviewing savings statistics."

Token-Saver Configuration & Diagnostics

Check Status

Run `token-saver stats` to see lifetime and per-command compression statistics. Add `--json` for machine-readable output.

Check Why a Specific Command Was (or Wasn't) Compressed

There is no `token-saver config` subcommand — use `explain` and `benchmark` instead:

token-saver explain "git status"          # routing decision: compressible? which processor? why excluded?
token-saver benchmark "npm install" --dry-run   # measure compression without replacing real output

Configuration

Settings are read in this order (later wins): built-in defaults → `~/.token-saver/config.json` → a project-level `.token-saver.json` found by walking up from cwd → `TOKEN_SAVER_*` environment variables. There is no CLI subcommand to write these files — edit `~/.token-saver/config.json` directly, or set an environment variable.

The most commonly adjusted settings and their actual defaults:

• `enabled` (bool, default `true`): master on/off switch.
• `min_input_length` (int, default `1`): minimum output length in characters before compression is attempted.
• `min_compression_ratio` (float, default `0.0`): a compression result below this fraction is discarded and the original output is returned instead.
• `wrap_timeout` (int, default `300`): max seconds a wrapped command may run before being killed.
• `chars_per_token` (int, default `4`): used only to estimate token counts for display (stats, benchmark) — not part of compression itself.
• `disabled_processors` (list, default `[]`): processor names (e.g. `"docker"`, `"kubectl"`) to turn off entirely.
• `max_output_bytes` (int, default `10_000_000`): hard cap on output length before compression even runs.

Example `~/.token-saver/config.json`:

{
  "min_compression_ratio": 0.1,
  "disabled_processors": ["docker"]
}

Equivalent environment variables: `TOKEN_SAVER_MIN_COMPRESSION_RATIO=0.1`, `TOKEN_SAVER_DISABLED_PROCESSORS=docker`.

**Security note:** `user_processors_dir`, `disabled_processors`, and `redaction_allowlist` can only be set via the global `~/.token-saver/config.json` or an environment variable — never via a project-level `.token-saver.json` (that file is auto-discovered from any directory you `cd` into, so it is not trusted with these).

See `src/config.py`'s `_DEFAULTS` dict for the full, authoritative list of settings — this file lists only the ones users actually tune.

Debug Mode

Set `TOKEN_SAVER_DEBUG=true` to enable debug logging to `~/.token-saver/hook.log` (or `%APPDATA%\token-saver\hook.log` on Windows).

Supported Processors

36 specialized processors, auto-discovered from `src/processors/`: git, gh (GitHub CLI), docker, kubectl, helm, terraform, pulumi, cdktf, ansible, nix, mise, npm/pip/cargo/go/maven/gradle/bun, package listing, python install, test runners (pytest, jest, go test, cargo test, …), lint output (eslint, ruff, pylint, clippy, …), build output, cloud CLIs (aws, gcloud, az), database queries, file listings, file content, environment/system info, network tools (curl, wget), search (grep, find, ripgrep), structured logs, syslog, ssh, jq/yq, act, just — plus a generic fallback for everything else.

Troubleshooting

If compression isn't working: 1. Check that `python3` (3.10+) is available in your PATH. 2. Run `token-saver explain "<the command>"` to see the routing decision and why it was or wasn't wrapped. 3. Set `TOKEN_SAVER_DEBUG=true`, trigger a compressible command, then check `~/.token-saver/hook.log` for errors. 4. Verify the hook itself responds correctly:

   echo '{"tool_name":"Bash","tool_input":{"command":"git status"}}' | python3 "${CLAUDE_PLUGIN_ROOT}/scripts/hook_pretool.py"

A working hook prints a JSON object with `hookSpecificOutput.updatedInput.command` rewritten to invoke `wrap.py`.