Documentation

Troxy makes your Claude Code subscription last longer. This page covers install, the Usage page and the CLI.

Quick Start

Get up and running in under 2 minutes.

Fastest: the Claude Code add-on (no terminal)

1. Sign in to the Troxy dashboard with Google or an email code.
2. In Claude Code (terminal or desktop app), type:

   /plugin install troxy-guard --marketplace troxy-hq/troxy-plugin

3. Type /reload-plugins. A line above the message box shows a link and a code, like Connect Troxy: open https://dash.troxy.io/activate?code=ABCD-1234 ...
4. Open the link, check the code matches, and click Connect. Troxy turns on within a few seconds. No key to copy.
5. Keep it up to date: type /plugin, open Marketplaces, pick troxy, and choose Enable auto-update. Claude Code leaves this off by default for marketplaces outside Anthropic's own.

No code shows after /reload-plugins? Update Claude Code first (claude update, or update the desktop app); older versions do not load add-ons.

Prefer the terminal? The CLI below sets up the same add-on plus a background service.

Prerequisites, Node.js 18+

The Troxy CLI requires Node.js. Run node -v, if you see a version number, skip ahead to Install the CLI below.

curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install -y nodejs

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo bash -
sudo apt-get install -y nodejs

brew install node

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
source ~/.bashrc
nvm install --lts

1. Install the CLI

sudo npm install -g troxy-cli

sudo will prompt for a password. That's your computer's own login password, not a Troxy password, and nothing will show on screen as you type it - that's normal, just type it and press Enter.

This makes the troxy command available globally. All examples below use troxy directly.

Already installed? Run troxy update to upgrade, or troxy --version to check what you have. If the update fails, see Update errors in Troubleshooting.

2. Get your API key

Log in to the Troxy dashboard, go to API Keys, and copy your API key. It starts with txy-.

3. Connect this machine (once)

troxy init --key txy-your-key-here

Afterwards Claude Code may ask you to sign in again. That is normal.

This will:

• Validate your API key and save it to ~/.troxy/config.json
• Ask you to name this machine (e.g. "Work Mac")
• Install a background service so Troxy survives reboots

You'll see a green dot next to this machine's name in the dashboard within 60 seconds. You only need to run this once per machine.

4. Log in for CLI commands (12-hour session)

troxy login

This opens your browser with a Troxy login page that displays a short code. Copy the code and paste it back into the terminal. You're then authenticated for 12 hours. This is separate from the API key and required to run the CLI inspection commands (activity, insights, usage-bar).

5. Watch your usage

Open the dashboard. The Usage page shows what Troxy saved you.

How it Works

Troxy adds a background service and a Claude Code add-on to your machine. The add-on can run a request on a lighter model and shorten bulky tool output; see Usage savings. Claude Code still talks to Anthropic directly. After each request, Troxy sends metadata (see What is sent) to your account, which powers the Usage page.

The service also sends a heartbeat every 60 seconds, which is what makes the green dot appear in your dashboard.

Where does Troxy work?

Usage savings in Claude Code

Troxy makes your Claude subscription last longer without changing what you ask Claude to do. It runs as a small add-on (a mod called troxy-guard) inside Claude Code. Your Claude login stays on your machine and Claude Code talks to Anthropic directly: nothing is routed through Troxy's servers, and there is no proxy and no certificate to install.

It does three things:

• Routes easy prompts to a lighter model (details).
• Can shorten large tool outputs, but this is off by default (details).
• Compacts an idle session so the next prompt does not re-send everything at full price (details).

troxy init installs the add-on into ~/.claude/skills/troxy-guard and troxy update keeps it current. A Claude Code session loads the add-on when it starts, so after an update run /reload-plugins in sessions that are already open.

Model routing

Before each prompt, a small Haiku call (made through your own Claude session) reads the first 4,000 characters and gives the prompt a difficulty score from 0 to 1. A score of 0.85 or below runs on Sonnet. A harder prompt stays on the model you chose.

• Never upward. Routing only moves down. If you chose Sonnet or Haiku, it stays there.
• Only at a cold moment. Anthropic's prompt cache is per model, so switching in the middle of a long conversation re-sends all of it at full price. Troxy picks by score only for the first prompt of a session, after 55 minutes idle, and after a compaction. Otherwise the session stays on the model it is already warm on.
• You are in charge. A model you pick with /model always wins.
• It fails open. If the scoring call fails or times out (3 seconds), your requested model is used.

Shorter tool outputs

Off by default. In our tests it made Claude re-run commands and re-read files, which cost more usage than it saved. Set TROXY_COMPRESS=1 to turn it on. When on, a large result from a Bash command or a file read is replaced with an excerpt and a short handle, for example (troxy_recall("1c3350444a5b1184") to fetch the full output). Claude can call the troxy_recall tool to get the full text whenever it needs it, or just the part it needs: lines (for example "120-180") or pattern (lines containing some text, with a few lines around each). Text fetched back goes into the conversation again, so the Usage page subtracts it from the saving. The shorter result also stays out of every later request in that session, which is where most of the saving comes from.

• The full output is stored on your machine in ~/.troxy/sandbox and never leaves it.
• Search results (Grep), file edits and results from other MCP tools are not shortened.
• This runs as a Claude Code hook that troxy init adds to ~/.claude/settings.json, so it works independently of the add-on's routing.

Idle compaction

Anthropic's cache expires after a while. If a session with 100k tokens or more has been idle for 55 minutes, Troxy compacts it, so your next prompt starts from a short summary instead of re-sending the whole conversation at full price. Turn it off with /troxy compact off.

Comparison sessions

To measure what Troxy really does, a share of sessions is kept as a comparison: about 1 in 10 sessions is never routed and about 1 in 5 keeps its full tool outputs. They are chosen at random and stay that way for the whole session. The status line says so when a session is not being routed. The dashboard compares them with the rest, so the numbers can be checked instead of taken on trust.

Controls

The line above the prompt reads like Troxy · 55% of this session ran on a lighter model · 5h: 34% used · 7d: 5% used. The first figure is the share of this session's requests that ran on a lighter model than you asked for. The usage figures are Anthropic's own.

What is sent to Troxy

Only metadata about each request, never your prompt, your code or Claude's reply: the model you asked for and the model that ran, token counts (input, output, cache), your usage-bar readings, a session id, which comparison group the session is in, the difficulty score, whether it came from the terminal or the desktop app, and how many tokens were shortened. It is sent to your Troxy account to power the Usage page. To stop it, set "reportUsage": false in ~/.troxy/config.json; routing and shortening keep working locally, and the Usage page stops updating.

Because Claude Code talks to Anthropic directly, Troxy never sees or stores your Claude login.

The Usage page

The Usage page in the dashboard shows what Troxy did and how the saving is worked out: how many requests ran on a lighter model, how many tokens were kept out, and where the saving came from. Every request is priced at Anthropic's list prices on the model that ran and on the model you asked for, weighted by how the usage bar charges each model. Tokens kept out by shortening tool outputs are priced as cache reads, once for the request that shortened them and again for each later request in the same session. That second part is an assumption, limited to what each later request actually read from the cache. The number is an estimate from list prices, not a reading of your usage bar. The 5-hour and weekly meters on the page are Anthropic's own.

Config file

Troxy stores its local config at ~/.troxy/config.json. You can view or edit it directly:

cat ~/.troxy/config.json

A typical config looks like this:

{
  "apiKey": "txy-your-key-here",
  "agentName": "Support Agent"
}

Changing the agent name

Edit the config file directly, then restart the service:

nano ~/.troxy/config.json

# After saving, restart:
sudo systemctl restart troxy-mcp        # Linux
launchctl unload ~/Library/LaunchAgents/ai.troxy.mcp.plist   # macOS
launchctl load  ~/Library/LaunchAgents/ai.troxy.mcp.plist

The dashboard will show the updated name within 60 seconds.

Environment variables

Environment variables take precedence over the config file, useful for containers or CI:

TROXY_API_KEY=txy-your-key TROXY_AGENT_NAME="Prod Agent" npx troxy-cli mcp

Re-running init

To start fresh (e.g. to swap API keys or rename the agent), uninstall first then re-run:

troxy uninstall
troxy init --key txy-your-new-key-here

Removing Troxy

There are two separate things you can do, and they're often confused, make sure you understand both:

After uninstalling, restart your AI client (Claude Desktop, Cursor, etc.) to fully stop the MCP server process.

API key vs login session, what requires what

troxy init connects this machine, that's it. The API key it saves is used only to send heartbeats and usage metadata. It cannot view your activity or manage your account.

troxy login gives you a 12-hour human session for everything else, all inspection commands go through this session, not the API key.

Bottom line: run troxy init once per machine to connect it, then run troxy login whenever you want to manage your account from the CLI. Sessions last 12 hours.

troxy init

Run once per agent. Validates the key, names this machine in your dashboard, and connects it to Troxy.

troxy init --key txy-your-key-here

After init, your key is saved to ~/.troxy/config.json, no need to pass --key to any other command.

Naming the agent

By default init asks for a name interactively, defaulting to the machine's hostname. Pass --name to skip the prompt. The name is what appears in your dashboard sidebar and on every decision the agent makes, so give each agent its own.

troxy init --key txy-your-key-here --name "Lyra SuperAgent"

What gets connected

Init saves your key, installs the background service, sets up the Claude Code add-on, and connects this machine to your dashboard.

Usage savings in Claude Code

If init detects Claude Code, it installs the usage-savings add-on and the tool-output hook (see Usage savings) and makes sure Claude Code talks to Anthropic directly. A setup left by an older Troxy version (a local proxy, a certificate, or a changed base URL) is removed automatically on init and on every troxy update. Nothing is intercepted, and your Claude login never leaves your machine.

Init no longer has a --proxy flag. To route an API key through Troxy's hosted proxy instead, see troxy proxy.

Repo instructions (--concise)

Init can also write a short Troxy section into your project's AGENTS.md (or a global one) so any agent working in the repo knows to check in. Choose project-scoped or global, or skip it:

troxy init --key txy-your-key-here --concise           # global (recommended default)
troxy init --key txy-your-key-here --concise project   # this repo only
troxy init --key txy-your-key-here --no-concise         # skip

Change it later the same way as proxy:

troxy concise status
troxy concise enable [--project]
troxy concise disable [--project]

troxy proxy

Experimental, for Claude API keys only. Routes Claude Code's calls through Troxy's hosted proxy so that routing applies to API-key traffic. A Claude subscription login (Pro, Max) is never sent to Troxy: Anthropic's terms do not allow a third party to handle it, so subscription users should leave this off and use the usage-savings add-on instead.

troxy proxy status
troxy proxy enable --help         # what it changes, before you run it
troxy proxy enable --experimental
troxy proxy disable

Enabling it writes HTTPS_PROXY and NODE_EXTRA_CA_CERTS into ~/.claude/settings.json, pointing at a certificate authority generated on this machine in ~/.troxy/tls/. Its private key never leaves the machine, it is restricted to api.anthropic.com, and it is never added to your system keychain. troxy proxy disable removes it. --experimental is required as an explicit acknowledgment.

troxy concise

Turns the Troxy section in AGENTS.md on or off without re-running init.

troxy concise status
troxy concise enable            # writes to the global AGENTS.md
troxy concise enable --project  # writes to this repo's AGENTS.md instead
troxy concise disable [--project]

troxy tools

Re-scans this machine for AI coding tools (Claude Code, Cursor, GitHub Copilot, Windsurf, Continue, Aider) and reports which ones it found to the dashboard's "My AI tools" view. Run this any time you install or remove one.

troxy tools

troxy slim

Claude Code loads every tool it has into each request, even ones you never use, and that part is re-read on every call. Turning off the ones you don't use makes each call lighter. With both of these off, a new session's first call went from about 52k to 37.5k tokens in our test.

• chrome: Claude in Chrome, which lets Claude control your browser.
• artifact: Artifacts, which lets Claude publish pages to claude.ai.

troxy slim                   # shows which are on or off
troxy slim chrome            # turn one off
troxy slim chrome --undo     # turn it back on

You don't have to do anything: troxy init (or your next troxy update) checks your Claude Code history on this machine once and turns off each tool you have never used. A tool you have used stays on. It prints one line for each tool it turned off, with the command to undo it, and your dashboard (Settings, My AI tools) shows which are on or off. The change is written to ~/.claude/settings.json, so it also applies to Claude Code in the desktop app. It takes effect in a new Claude Code session. Troxy also adds a short note to ~/.claude/CLAUDE.md listing what it turned off, so if you ask Claude for one of these tools it tells you the command to turn it back on. troxy uninstall turns them back on.

troxy update

Updates the Troxy CLI to the latest version from npm.

troxy update

Don't use sudo troxy update. If npm needs admin rights, troxy update asks for your password for the npm step only, so nothing in your home folder ends up owned by root. After updating, run troxy restart to apply the new version to the background service.

troxy update
troxy restart

troxy restart

Restarts the Troxy background service. Use this after updating or after manually editing ~/.troxy/config.json.

troxy restart

troxy uninstall

Fully removes Troxy from the current machine and revokes the API key server-side.

troxy uninstall

This command does the following:

1. Calls POST /mcp/self-revoke to revoke the API key on the server
2. Stops and removes the background MCP service
3. Removes the troxy-mcp entry from all detected client configs (Claude Desktop, Cursor, Windsurf)
4. Deletes ~/.troxy (your local config and saved API key)

After running: restart your AI client (Claude Desktop, Cursor, etc.) so the MCP server process fully stops. Until you restart, the client may still try to connect.

Want to reinstall later? Just create a new API key in the dashboard and run troxy init --key txy-your-key. Your dashboard data is untouched.

Remove the CLI and Node.js

Run troxy uninstall first (above), then remove the CLI package. Removing Node.js is optional and only needed if you installed it just for Troxy.

macOS / Linux

sudo npm uninstall -g troxy-cli

Node.js, if you want it gone: brew uninstall node (Homebrew), sudo apt remove nodejs (Ubuntu / Debian), sudo yum remove nodejs (Amazon Linux / RHEL / CentOS), or nvm uninstall <version> (nvm).

Windows (Command Prompt)

npm uninstall -g troxy-cli
rmdir /s /q "%APPDATA%\npm"

Windows (PowerShell)

npm uninstall -g troxy-cli
Remove-Item -Recurse -Force "$env:APPDATA\npm"

Node.js, if you want it gone: open Settings, Apps, Installed apps, find Node.js and choose Uninstall.

troxy login / logout

Authenticates you as a human for 12 hours. Required for every command except troxy init and troxy status, activity, insights, usage-bar, rotate-key, all of it.

troxy login
troxy logout

After running troxy login:

1. Your browser opens to the Troxy login page
2. Log in, and the page shows you a short code
3. Copy the code and paste it back into the terminal
4. You're authenticated for 12 hours

troxy status

Shows API health and connection status. Works without login. If you're logged in, also shows your account overview (an overview).

troxy status

troxy activity

Shows recent decisions across all your MCPs. Requires a login session.

troxy activity
troxy activity --limit 50      # show more rows (default: 20, max: 200)
troxy activity --mine          # show only decisions made by the MCP on this machine

--mine filters to decisions made by the MCP key configured on this machine via troxy init. Only works on a machine that has an MCP key configured.

troxy insights

Shows a summary of your requests for a given period. Requires a login session.

troxy insights              # last 30 days
troxy insights --period 7   # last 7 days

troxy usage-bar

Shows what Troxy's model routing (and shortened tool outputs, if you turned them on) actually did for your Claude Code usage over a given period. Requires a login session.

troxy usage-bar              # last 30 days
troxy usage-bar --period 7   # last 7 days

Reports real counts (requests seen, how many ran on a lighter model, how many tokens were kept out) rather than one shared percentage. How much longer this makes your bar last depends on your own mix of work. The Usage page in the dashboard shows the same data with an estimate and an explanation of how it is worked out.

troxy rotate-key

Creates a new API key, saves it to ~/.troxy/config.json, and immediately revokes the old one. Requires login.

troxy rotate-key                    # rotate key (old is revoked automatically)
troxy rotate-key --name "new name"  # give the new key a custom name

After rotating, restart the MCP service to pick up the new key:

troxy restart

Auto-start on reboot

troxy init installs a background service that starts automatically at boot.

# Linux, manage the service
sudo systemctl status troxy-mcp
sudo systemctl restart troxy-mcp
sudo systemctl stop troxy-mcp

# View live logs
journalctl -u troxy-mcp -f

# macOS, manage the LaunchAgent
launchctl list | grep troxy
launchctl unload ~/Library/LaunchAgents/ai.troxy.mcp.plist
launchctl load  ~/Library/LaunchAgents/ai.troxy.mcp.plist

Troubleshooting

Dashboard shows "MCP disconnected"

The MCP service isn't running or hasn't sent a heartbeat yet (every 60 seconds).

# Check status
sudo systemctl status troxy-mcp

# Restart
sudo systemctl restart troxy-mcp

# Watch live logs, you should see "[troxy] heartbeat ok" every 60s
journalctl -u troxy-mcp -f

The dashboard dot updates within 60 seconds of the next heartbeat.

Machine name shows as "unknown" in activity

Requests logged before you set a name won't have one. New ones use the name from your config. Edit ~/.troxy/config.json and restart the service.

CLI shows "authentication required" or "login required"

troxy login

All CLI commands other than troxy init and troxy status require a login session. Run troxy login to start one.

API key invalid or revoked

If you see "API key invalid or revoked", your saved key is no longer accepted. Generate a new key in the dashboard under API Keys, then reconnect:

troxy init --key txy-your-new-key-here

Service fails to start (wrong binary path)

If journalctl -u troxy-mcp shows "command not found", the service was installed with an incorrect path. Fix it:

troxy uninstall
troxy init --key txy-your-key-here

npm permission error during install

If you see EACCES: permission denied when installing globally:

sudo npm install -g troxy-cli

The Troxy line above the prompt is missing, or the Usage page shows nothing new

Check three things. First, claude --version must be 2.1.287 or newer. Second, run troxy update, then /reload-plugins in the Claude Code session: a session only loads the add-on when it starts or is reloaded. Third, make sure the work is in Claude Code (terminal or the desktop app's Code tab), since chat is not covered.

Claude Code can't reach Anthropic after an older Troxy install

Older versions pointed Claude Code at a local proxy. Run troxy update (or troxy init) to remove it, or troxy proxy disable. Then restart Claude Code.

Update errors

If troxy update fails with a permission error, run it again without sudo; it asks for your password for the npm step only. If it fails with ENOTEMPTY, remove the package manually and reinstall:

sudo rm -rf /opt/homebrew/lib/node_modules/troxy-cli && sudo npm install -g troxy-cli@latest

Check API health

troxy status