Codex (CLI)

Installing for Codex is two steps: add the marketplace plugin, then run the one-time codex-install command to wire the hooks. The plugin alone does not install the hooks; the command does. Every Codex engine command needs the TOKEN_OPTIMIZER_RUNTIME=codex prefix so it reads Codex data, not Claude Code data.

Prerequisites

Codex CLI or Codex Desktop.
Python 3.9 or newer on your PATH.

Install the plugin

codex plugin marketplace add alexgreensh/token-optimizer

Then in the Codex TUI, open /plugins and install Token Optimizer. Invoke it conversationally: “Run Token Optimizer”.

Wire the hooks

This step is required. It writes the hooks to ~/.codex/hooks.json, which Codex loads for all projects regardless of trust level.

Install globally, for all projects:

TOKEN_OPTIMIZER_RUNTIME=codex python3 skills/token-optimizer/scripts/measure.py codex-install

Or scope it to one project instead:

TOKEN_OPTIMIZER_RUNTIME=codex python3 skills/token-optimizer/scripts/measure.py codex-install --project "$PWD"

Hook profiles

codex-install defaults to the balanced profile. Pass --profile to pick another based on how much hook activity you want.

Profile	What it installs	Noise level
`balanced` (default)	SessionStart + UserPromptSubmit + Stop + compact prompt	Low, 3 hook events
`quiet`	Stop only	Minimal, 1 hook event
`telemetry`	Balanced + PostToolUse	Medium, visible rows in Desktop
`aggressive`	All hooks including experimental Bash PreToolUse	High, full coverage

Install with a specific profile:

TOKEN_OPTIMIZER_RUNTIME=codex python3 skills/token-optimizer/scripts/measure.py codex-install --profile quiet

Set up the dashboard

The Codex dashboard runs on port 24843, separate from Claude Code’s 24842, so both can run at once.

TOKEN_OPTIMIZER_RUNTIME=codex python3 skills/token-optimizer/scripts/measure.py setup-daemon

Open it at http://localhost:24843/token-optimizer. The file fallback lives at ~/.codex/_backups/token-optimizer/dashboard.html. For LAN access, set TOKEN_OPTIMIZER_DASHBOARD_HOST=0.0.0.0 before running setup-daemon; the setting is sticky and independent per runtime.

Verify

Run the doctor. A healthy install reports 0 FAIL.

TOKEN_OPTIMIZER_RUNTIME=codex python3 skills/token-optimizer/scripts/measure.py codex-doctor --project "$PWD"

Other useful checks:

TOKEN_OPTIMIZER_RUNTIME=codex python3 skills/token-optimizer/scripts/measure.py report
TOKEN_OPTIMIZER_RUNTIME=codex python3 skills/token-optimizer/scripts/measure.py dashboard --quiet

Inside Codex, you can also say “Run Token Optimizer”, “Run Token Coach”, “Run Fleet Auditor”, or “Show the dashboard”.

Auto-update

Codex auto-upgrades Git-backed marketplaces on startup via git ls-remote. To update by hand:

codex plugin marketplace upgrade

Uninstall

Remove the dashboard daemon, then remove the plugin via the Codex /plugins menu:

TOKEN_OPTIMIZER_RUNTIME=codex python3 skills/token-optimizer/scripts/measure.py setup-daemon --uninstall

To strip the hooks, delete the Token Optimizer entries from ~/.codex/hooks.json (or the per-project file if you scoped it).