token-saver-config

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).