Claude Code (cloud sessions)

Claude Code cloud sessions (claude.ai/code, and claude --cloud) run in a fresh VM. They load no plugins at all: not the ones installed on your machine, not ones enabled in a repository’s .claude/settings.json. What a cloud VM does run is your environment’s setup script, and the hooks in the VM’s own ~/.claude/settings.json. Token Optimizer uses both.

Set it up once per environment

On a machine where Token Optimizer is installed, print the setup script for your version:
```
python3 measure.py cloud-setup-script
```
(Or ask Claude: “print the Token Optimizer cloud setup script”.) The output is three lines: two comments and one command.
On claude.ai/code, open your environment’s settings and paste those lines into Setup script. Keep anything else you already have there; the lines never stop the rest of your script from running.
Start a session. That’s it. Every session in that environment, in any repository, runs Token Optimizer.

No per-repository setup, and nothing is committed to your repositories.

How it works

The setup script downloads @alexgreensh/token-optimizer from registry.npmjs.org. The npm package is the Claude Code plugin itself, version for version: the same hooks and scripts.
It checks the tarball’s sha512 against the value printed into the script. If they don’t match, nothing in the tarball runs.
It runs the package’s install-cloud.sh, which copies Token Optimizer to ~/.cache/token-optimizer-cloud/<version> in the VM and merges hooks into the VM’s ~/.claude/settings.json. The hook list is generated from the plugin’s own hooks/hooks.json, so cloud sessions run exactly the hooks a desktop install runs, with the same matchers and timeouts. Existing settings are merged, never overwritten.
In the session, each hook calls a small runner that points CLAUDE_PLUGIN_ROOT at the installed copy and starts the real hook. Compression, read dedup, the tool-result archive and measure.py expand, checkpoints and compaction restore all work as they do on your machine.

The setup script always succeeds, even if the registry is unreachable, and prints nothing. Its log is ~/.cache/token-optimizer-cloud/install.log in the VM.

Pinned or latest

By default the script pins the version you printed it from, plus that version’s sha512. The code that runs is fixed until you paste a new script. To update, run cloud-setup-script again after updating Token Optimizer and replace the lines.

python3 measure.py cloud-setup-script --latest prints a script that follows the newest published version instead. Plainly: it trusts whatever is published on npm as @alexgreensh/token-optimizer. It checks each download against the sha512 the registry publishes for it, which proves the bytes arrived intact, not who published them, so anyone who gained publish rights on the package could ship code into every environment that uses --latest. The pinned default only runs the exact bytes you printed the script for. Cloud environments cache their setup for about a week, so either way a new version arrives when the environment rebuilds.

Startup cost

The setup script runs when the environment is built, before Claude Code starts, not at every session: one ~1.6 MB download plus a short install (0.8 s on a Mac in testing; not yet timed inside a cloud VM). During a session, hooks cost what they cost on your desktop.

Limits

Nothing persists across sessions yet. Trends, the session database, checkpoints and the dashboard live in the VM and go away with it. Each session starts clean.
The dashboard can be generated in the VM (measure.py dashboard), but there is no browser to show it in. Use your local install for history.
Cowork cloud tasks are a separate setup; see Cowork.

Check it, or turn it off

From inside a cloud session:

python3 ~/.cache/token-optimizer-cloud/*/skills/token-optimizer/scripts/measure.py cloud-doctor

It checks the install, that the hooks in settings still match hooks.json, and names the live route: the hooks in ~/.claude/settings.json (what the setup script writes), the managed fallback below, the Token Optimizer plugin itself (when account plugin sync delivers it, the cloud hooks stand down), or none. If the setup script ran but the hooks are missing from ~/.claude/settings.json in the session, it says so in plain words: something rewrote the file after the setup script.

Managed fallback (optional)

python3 measure.py cloud-setup-script --managed-fallback adds one step: the same hooks are also written to /etc/claude-code/managed-settings.d/50-token-optimizer-cloud.json, Token Optimizer’s own drop-in file in Claude Code’s managed settings directory. If anything rewrites ~/.claude/settings.json after the setup script, the hooks still load from there. Claude Code runs a handler defined in more than one settings file once, and the two copies are identical, so nothing runs twice. No other file in that directory, and never managed-settings.json, is touched; removing the kit deletes only this file.

It is off by default for a reason: Claude Code documents reading the managed settings file for self-hosted environments (and only when no server-managed settings or MDM policy supply the managed tier), while Anthropic-hosted sessions take policy from server-managed settings. Today’s Anthropic-hosted VMs start with no ~/.claude/settings.json and keep their own hooks in a separate file, so the default route has nothing to collide with.

Set TOKEN_OPTIMIZER_CLOUD_KIT=off in the environment’s variables to switch the hooks off without touching the setup script, or delete the lines to remove it.
Outside a cloud VM the hooks do nothing, and if the real plugin is ever loaded in the same VM (an account-synced copy, for example), the cloud hooks stand down so nothing runs twice.