tokendiet

Token optimization gateway CLI for Claude Code. Runs as a local proxy between Claude Code and the Anthropic API, measuring your token usage and applying deterministic, cache-safe optimizations before each request — without changing how you work. Stronger token-reduction strategies are available opt-in (see Stripping strategies).

Install

npm install -g tokendiet

Or run directly with npx:

npx tokendiet@latest start

Usage

# Start the gateway
tokendiet start --org-token <token>

# Start with custom options
tokendiet start --org-token <token> --port 3200 --verbose

# Dry-run mode (no stripping — measure baseline)
tokendiet start --org-token <token> --dry-run

# Stop the gateway and restore Claude settings
tokendiet stop

If you don't pass --org-token, the CLI will check for a saved token or prompt you interactively.

Commands

| Command | Description | | ------- | ---------------------------------------------------- | | start | Start the local TokenDiet gateway | | stop | Stop the running gateway and restore Claude settings |

Start options

| Flag | Default | Description | | --------------------- | --------------------------------------------- | ------------------------------------------------ | | --org-token <token> | — | Your organization API token | | --cloud-url <url> | https://tokendiet-production.up.railway.app | Cloud API URL | | --port <port> | 10741 | Port to listen on | | --verbose | off | Show full NestJS logs | | --dry-run | off | Disable all optimizations (baseline measurement) |

Stop options

| Flag | Default | Description | | --------------- | ------- | ------------------------------ | | --port <port> | 10741 | Port the gateway is running on |

How it works

1. Starts a local proxy on localhost:10741
2. Patches ~/.claude/settings.json to route Claude Code traffic through it
3. Applies its enabled optimization strategies to each request before forwarding to Anthropic (cache-safe by default — see below)
4. Reports token savings to the cloud API
5. Displays live savings in the terminal and on a local stats page at http://localhost:10741/ui
6. Restores original Claude settings on exit (Ctrl+C) or tokendiet stop

Token resolution order

1. --org-token CLI flag (highest priority)
2. Saved token from ~/.tokendiet/.env
3. Interactive prompt

If a token is rejected (401), the saved token is cleared and you're prompted again.

Stripping strategies

All strategies are deterministic and idempotent — they never change the semantic meaning of your requests. By default the gateway runs in a conservative, cache-safe mode: it only normalizes tool-result ordering and forwards everything else unchanged. Stronger token-reduction strategies are opt-in via environment variables.

On by default

| Strategy | Env flag | What it does | | ---------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Tool-result reordering | STRIP_TOOL_RESULT_ORDER | Normalizes the order of parallel tool_result blocks so they don't orphan the prompt cache. Removes no content — improves cache hit rate. |

Opt-in (off by default)

Set the env flag to true before tokendiet start to enable. These remove or compress content, so turn them on deliberately:

| Strategy | Env flag | What it does | | --------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | Whitespace normalization | STRIP_WHITESPACE | Collapses unnecessary whitespace in message content and tool results | | Stale-read compression | STRIP_STALE_READS | Compresses file reads that have been superseded by newer reads (cache-aware) | | Bash-log compression | STRIP_BASH_LOGS | Truncates long Bash command output | | Subagent-output compression | STRIP_AGENT_COMPRESSOR | Truncates large code blocks in subagent (Agent tool) results | | Tool-schema stripping | STRIP_SYSTEM_AND_TOOLS | Enables a set of safe tool-schema reductions (descriptions, titles, examples, duplicate phrases) from the tools array |

Example:

STRIP_WHITESPACE=true STRIP_SYSTEM_AND_TOOLS=true tokendiet start --org-token <token>

Data & Privacy

TokenDiet is designed so that your prompts, code, and conversation content never leave your machine via TokenDiet.

What stays on your machine

• Your Anthropic API key — passed directly to Anthropic, never sent to TokenDiet servers
• All prompt and message content — the full request body goes straight to the Anthropic API
• Your code and file contents — TokenDiet strips tokens locally but never reads or stores your code

What is sent to the TokenDiet cloud API

Only usage metadata is reported, so we can calculate your savings:

• Token counts (original, stripped, and actual from the API response)
• Model name (e.g. claude-opus-4-6)
• Cache usage statistics (read/write token counts)
• Which stripping strategies were applied and how many tokens they reduced
• Gateway version and request timestamp
• A session identifier (random UUID) to group requests within the same Claude Code conversation for accurate savings tracking — this ID contains no personal information

What is never sent

• Message content, prompts, or system instructions
• Code, file contents, or tool results
• Your Anthropic API key

Local storage

• Your org token is saved to ~/.tokendiet/.env (file permissions: owner-only read/write)
• Claude Code settings are temporarily patched while the gateway runs and restored on exit

Development

# Build and run the CLI with dev defaults (localhost:3001 cloud API)
npm run start

License

MIT