Claude Code (CLI)

Use the plugin install on every operating system, including Windows. The script install is a macOS and Linux alternative for people who want a Git-backed checkout that re-runs daily. Pick one. Running both on the same machine doubles the hooks and the session writes.

Prerequisites

Claude Code CLI, current version.
Python 3.9 or newer on your PATH (the engine is pure standard library, no pip install).
For the script install only: git, curl, and sha256sum or shasum (macOS and Linux).

/plugin marketplace add alexgreensh/token-optimizer
/plugin install token-optimizer@alexgreensh-token-optimizer

Then run your first audit:

/token-optimizer

The plugin lands in ~/.claude/plugins/marketplaces/alexgreensh-token-optimizer. Its hooks auto-activate on install. No manual hook setup.

The script clones the latest release tag and verifies the install.sh checksum before executing it.

tmp="$(mktemp -d)"
release_json="$(curl -fsSL https://api.github.com/repos/alexgreensh/token-optimizer/releases/latest)"
tag="$(python3 -c 'import json,sys; print(json.load(sys.stdin)["tag_name"])' <<<"$release_json")"
checksums="$(python3 -c 'import json,sys; data=json.load(sys.stdin); print(next(a["browser_download_url"] for a in data["assets"] if a["name"]=="CHECKSUMS.sha256"))' <<<"$release_json")"
git clone --branch "$tag" --depth 1 https://github.com/alexgreensh/token-optimizer.git ~/.claude/token-optimizer
curl -fsSL -o "$tmp/CHECKSUMS.sha256" "$checksums"
install_sum="$(grep '  install.sh$' "$tmp/CHECKSUMS.sha256")"
(cd ~/.claude/token-optimizer && (printf '%s\n' "$install_sum" | sha256sum -c - --quiet 2>/dev/null || printf '%s\n' "$install_sum" | shasum -a 256 -c - --quiet))
bash ~/.claude/token-optimizer/install.sh
rm -rf "$tmp"

The script install destination is ~/.claude/token-optimizer/ and it symlinks the skill into ~/.claude/skills/token-optimizer. To skip checksum verification, set TOKEN_OPTIMIZER_SKIP_VERIFY=1 before running.

Enable auto-update

Auto-update is off by default for plugins, and plugin authors cannot change that default. Turn it on once:

/plugin  →  Marketplaces tab  →  alexgreensh-token-optimizer  →  Enable auto-update

The script install handles updates differently. It re-runs the installer daily against the latest release tag and re-verifies the checksum each time.

Claude Code cloud sessions

Cloud sessions on claude.ai/code run in a fresh container. They do not read the plugins installed on your own machine, and the /plugin command is not available inside them, so the install above does not carry over. Two ways to get Token Optimizer into cloud sessions:

Per account: enable Token Optimizer for your claude.ai account (Desktop app, Customize, plugins). Claude Code then loads it in every cloud session as a synced plugin.
Per repository: commit the following to the repository’s .claude/settings.json. Every cloud session on that repository installs the plugin at start (the default network level already allows GitHub).

{
  "extraKnownMarketplaces": {
    "alexgreensh-token-optimizer": { "source": { "source": "github", "repo": "alexgreensh/token-optimizer" } }
  },
  "enabledPlugins": { "token-optimizer@alexgreensh-token-optimizer": true }
}

Inside the session, claude plugin list shows the plugin, and any Bash command with long output shows the usual compression banner. Hooks, compression and redaction behave exactly as they do locally. One difference: each cloud session starts with an empty state directory, so the dashboard and audit history cover that session only; nothing is shared across sessions or with your machine.

Windows note

Windows is plugin path only. Do not run install.sh on Windows; Git Bash holds file handles and the install fails with EBUSY errors. A manual ZIP fallback is available from GitHub Releases.

On Windows, call the engine with python, not python3:

python measure.py doctor

Post-install setup

Both steps are optional. The status line auto-installs when your statusLine slot is empty, via the SessionStart ensure-health hook.

Install the quality status line manually (only if the auto-install did not run):
Terminal window
```
python3 measure.py setup-quality-bar
```
Set up the bookmarkable dashboard daemon so the URL stays live between sessions:
Terminal window
```
python3 measure.py setup-daemon
```
This supports macOS (launchd), Linux (systemd —user), and Windows (Task Scheduler). For LAN access, set TOKEN_OPTIMIZER_DASHBOARD_HOST=0.0.0.0 before running it. See Configuration for the full variable list.

Verify

python3 measure.py doctor

Or inside Claude Code, run /token-optimizer for the full guided audit. The dashboard lives at http://localhost:24842/token-optimizer and falls back to a generated dashboard.html when the daemon is not running.

Uninstall

/plugin uninstall token-optimizer@alexgreensh-token-optimizer

Remove the dashboard daemon first if you installed it:

python3 measure.py setup-daemon --uninstall

For the script install, delete ~/.claude/token-optimizer/ and the ~/.claude/skills/token-optimizer symlink. To remove the status line, run python3 measure.py setup-quality-bar --uninstall.