Every command, setting, CLI flag, and environment variable TokenBeaver understands — across both surfaces (the VS Code extension and the standalone gateway CLI) and the localhost Settings page they share.
The VS Code extension and the CLI (@tokenbeaver/gateway) both drive the exact same local gateway. Its base URL is always http://127.0.0.1:4505/v1 (port 4505 by default). Use whichever surface fits how you work — the settings that matter for optimization live in one shared place.
Same gateway and dashboard as the extension, driven from your shell. See Gateway CLI and environment variables.
Install tokenbeaver.tokenbeaver. See Command Palette and VS Code settings.
Optimization settings — provider, port, the compaction/output toggles, tool budgets — are not VS Code settings. They live on the localhost Settings page (open with --settings or TokenBeaver: Settings) and are shared across both surfaces via config.json. See the Settings page section below.
Open the Command Palette with Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS) and type "TokenBeaver" to see all of these.
| Command ID | Palette title |
|---|---|
tokenbeaver.openSettings | TokenBeaver: Settings |
tokenbeaver.openAccount | TokenBeaver: Account |
tokenbeaver.openHelp | TokenBeaver: Help & Setup |
tokenbeaver.openFeedback | TokenBeaver: Feedback & Support |
tokenbeaver.enterLicense | TokenBeaver: Activate or Upgrade to Pro |
tokenbeaver.showStatusInfo | TokenBeaver: Show Status Info |
tokenbeaver.copyShareSnippet | TokenBeaver: Copy Shareable Savings |
tokenbeaver.openDashboard | TokenBeaver: Open Cost Dashboard |
tokenbeaver.gateway.start | TokenBeaver: Start Gateway |
tokenbeaver.gateway.stop | TokenBeaver: Stop Gateway |
tokenbeaver.gateway.copyBaseUrl | TokenBeaver: Copy Gateway Base URL |
tokenbeaver.gateway.status | TokenBeaver: Gateway Status |
tokenbeaver.gateway.setup | TokenBeaver: Agent Setup Instructions |
tokenbeaver.claudeCode.repairHooks | TokenBeaver: Repair Claude Code Hooks |
tokenbeaver.openBillingPortal | TokenBeaver: Manage Subscription |
The status bar shows one item — ⚡ TokenBeaver — that opens the dashboard on click and displays your plan: Free, Pro, or Dev.
Only these live in VS Code (search "tokenbeaver" in Settings, or edit settings.json). Everything about optimization lives on the Settings page instead.
| Setting | Default | What it does |
|---|---|---|
tokenbeaver.workerUrl | "" → api.tokenbeaver.ai | Backend URL for licensing / billing |
tokenbeaver.gateway.autoStart | true | Start or attach the gateway when VS Code opens |
tokenbeaver.notifications.planAlerts | true | Occasional plan notifications |
tokenbeaver.urls.feedback | tokenbeaver.ai/feedback | Target for the Feedback & Support command |
tokenbeaver.legal.termsUrl / .privacyUrl | /terms · /privacy | Legal links used in the UI |
Provider, port, the optimization toggles and tool budgets are no longer VS Code settings — they're on the localhost Settings page, shared across the extension and CLI. This keeps one source of truth no matter which surface you started the gateway from.
The standalone gateway runs anywhere Node runs — same gateway and dashboard as the extension. Install with npm i -g @tokenbeaver/gateway.
| Command | What it does |
|---|---|
| Setup | |
tokenbeaver-gateway | Start the gateway; the first run asks for Terms consent and your use case |
--accept-terms | Accept Terms + Privacy non-interactively (enables optimization) — for scripts / CI |
--dashboard | Open the savings dashboard (http://127.0.0.1:4505/) |
--account | Open the Account page (/account) |
--settings | Open the Settings page (/settings) |
--help-page | Open the Help & Setup page (/help) with live checks |
--status | Show plan, consent, persona, and lifetime savings |
--install-claude-hooks | Wire Claude Code — hooks + the MCP restore tool |
--uninstall-claude-hooks | Remove TokenBeaver hooks from Claude Code |
--autostart <install|remove|status> | Manage launch-at-login |
| Account | |
--activate <token> | Activate Pro with an activation token |
--upgrade | Open checkout to upgrade to Pro |
--activate-email | Recover Pro on a new machine via your purchase email |
| Metrics | |
--report | Print the lifetime + per-session savings report |
--reset-metrics | Reset all recorded metrics |
--help | Show help |
Environment variables configure the standalone gateway process. Precedence is env > config.json > default — an env var wins over a Settings-page value.
| Env var | Default | What it does |
|---|---|---|
TOKENBEAVER_GATEWAY_PORT | 4505 | Listen port |
TOKENBEAVER_GATEWAY_PORT_STRATEGY | auto-detected | strict (fail if busy) · auto (scan for free port) · reuse (attach to existing gateway) |
TOKENBEAVER_PROVIDER | openrouter | Upstream provider (openrouter / openai / anthropic / custom / copilot) |
TOKENBEAVER_UPSTREAM_BASE_URL | — | Explicit upstream base URL (required for custom) |
TOKENBEAVER_ANTHROPIC_UPSTREAM_BASE_URL | — | Anthropic upstream for dual-upstream — routes /v1/messages |
TOKENBEAVER_TIMEOUT_MS | 60000 | Upstream request timeout |
TOKENBEAVER_ACCEPT_TERMS | — | 1 accepts the Terms non-interactively |
TOKENBEAVER_USECASE | asked on first run | cost · capacity · both |
TOKENBEAVER_READ_DEDUP | on | off stops skipping re-sends of unchanged file reads |
TOKENBEAVER_STRUCTURAL_COMPACTION | on | off turns off structural slimming of context |
TOKENBEAVER_RECOVERABLE | on | off turns off on-demand restore of slimmed content |
TOKENBEAVER_LEAN_OUTPUT | off | on slims tool output — nothing lost, restorable on demand |
TOKENBEAVER_CODE_COMPACTION_ENABLED | true | false sends code-like content untouched |
TOKENBEAVER_TOOL_BUDGETS | per-tool caps | Override per-tool output caps, e.g. bash:100,grep:50 |
TOKENBEAVER_TELEMETRY_DISABLED | — | 1 turns off pseudonymous usage telemetry |
Open it with tokenbeaver-gateway --settings or TokenBeaver: Settings. It's the shared home for optimization toggles — changes are saved to config.json and apply to both surfaces. Some optimizations are always-on internals and aren't exposed as switches; the "Settings page?" column says which you can toggle there.
| Feature | Default | Env var | On Settings page? |
|---|---|---|---|
| Read dedup | ON | TOKENBEAVER_READ_DEDUP | No — always-on internal |
| Structural compaction | ON | TOKENBEAVER_STRUCTURAL_COMPACTION | No |
| Recoverable compaction | ON | TOKENBEAVER_RECOVERABLE | No — gates the MCP restore tool |
| Lean output | OFF | TOKENBEAVER_LEAN_OUTPUT | Yes |
| Code folding | ON | TOKENBEAVER_CODE_COMPACTION_ENABLED | Yes |
| Tool line budgets | baked caps | TOKENBEAVER_TOOL_BUDGETS | Yes |
| Telemetry opt-out | opted-IN | TOKENBEAVER_TELEMETRY_DISABLED | Yes |
When an environment variable is set for a toggle, the Settings page shows an env: badge on that field and the env value wins — that's the env > config.json > default precedence in action. Unset the variable to edit the value from the page again. Provider changes are restart-required.
Open a GitHub issue → · Questions? Support
Email [email protected] or visit the support page — a real developer will get back to you.