Tokenoptimiser CLI

Tokenoptimiser reduces repeated context sent by AI coding agents without requiring changes to your project.

Quick start

npx tokenoptimiser connect claude

The first install provisions an isolated Python 3.13 runtime under ~/.tokenoptimiser. Tokenoptimiser downloads only version-pinned runtime artifacts and checks their SHA-256 hashes before use.

Supported platforms

| Operating system | Architectures | Minimum | | --- | --- | --- | | macOS | Apple Silicon, Intel | A Node.js 18+ compatible macOS release | | Windows | x64 | Windows 10 or 11 | | Linux | x64, ARM64 | glibc 2.28 |

Alpine/musl Linux and Windows ARM64 are not supported by the current native engine release. Node.js 18 or newer is required on every platform.

Commands

tokenoptimiser connect <agent> [args]  Run an agent through Tokenoptimiser
tokenoptimiser disconnect <agent>     Remove Tokenoptimiser routing from an agent
tokenoptimiser activate [key]         Activate Pro (hidden prompt when key is omitted)
tokenoptimiser recover                Recover and activate a crypto purchase
tokenoptimiser deactivate             Release this installation's license slot
tokenoptimiser stats                  Show this month's savings
tokenoptimiser report                 Open the local savings report

Agents

tokenoptimiser connect --help lists every supported agent: aider, claude, cline, codex, continue, copilot, cursor, goose, openclaw, opencode, openhands, vibe.

disconnect covers claude, codex, copilot, openclaw and opencode. Cursor reads its endpoint from its own settings UI rather than from a file Tokenoptimiser owns, so tokenoptimiser disconnect cursor prints the revert steps instead of performing them. The remaining agents are configured per-session and need no disconnect.

report builds a self-contained HTML file from the recorded savings history and opens it. It reads only ~/.tokenoptimiser/savings_events.jsonl, so it works offline and needs no agent session running. --no-open writes the file and prints its path instead.

Sessions in the report are reconstructed rather than recorded: the ledger stores a timestamp and an agent per event but no session id, so one agent's events are split wherever it went quiet for an hour. Every figure is a context (input) token saving. Output reduction is enabled separately, but it is not measured by the savings ledger and is therefore not included in the report totals.

Tokenoptimiser reduces output tokens by default as well as compressing input context. Its native defaults use verbosity level 2 and lower effort on structurally routine tool-result continuations; new questions and errors retain full effort. Override the behavior when launching a session:

TOKENOPTIMISER_OUTPUT=0 tokenoptimiser connect claude       # disable output shaping
TOKENOPTIMISER_VERBOSITY=3 tokenoptimiser connect claude    # stronger brevity
TOKENOPTIMISER_EFFORT=0 tokenoptimiser connect claude       # keep full reasoning effort

Verbosity levels range from 0 to 4. Set these variables before connect; they are also synchronized into a compatible proxy that is already running.

For Codex, connect temporarily updates the shared Codex provider configuration so WebSocket traffic reaches the local proxy. Tokenoptimiser restores the previous configuration when the connected Codex process exits. Restart an already-running Codex Desktop app after a connect starts or stops so it reloads that provider.

Tokenoptimiser stores its local runtime and configuration under ~/.tokenoptimiser (%USERPROFILE%\.tokenoptimiser on Windows). Set TOKENOPTIMISER_HOME to override that location.

Pro activations are bound to the installation and verified locally with a short-lived, server-signed entitlement. A network outage does not interrupt an already verified activation before its signed expiration.

Prefer tokenoptimiser activate without an argument: the interactive prompt does not echo the key or place it in shell history. A crypto checkout also provides a separate recovery code/file; tokenoptimiser recover accepts that code through the same hidden input and activates the recovered license.

Savings events are aggregated from ~/.tokenoptimiser/savings_events.jsonl by UTC month. connect synchronizes the absolute total after the agent exits and stats synchronizes before displaying it, so retries cannot double-count. The 10M free allowance currently counts reversible input compression only; output-token reduction is additional and does not consume that allowance.

For product information and early access, visit tokenoptimiser.io.