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 aggressive. Pass --profile to choose event coverage. Compact-prompt guidance is installed separately on every profile unless --skip-compact-prompt is set.

Bash PreToolUse rewriting is off on all profiles; opt in with --enable-bash-compression. --no-subagent-hooks removes subagent coverage. The PostToolUse hook is Bash-only and silent: it records thrash/archive state but does not emit Codex-unsupported updatedToolOutput.

Profile	Events installed	Behavior
`aggressive` (default)	SessionStart, UserPromptSubmit, SubagentStart, SubagentStop, PostToolUse (Bash), Stop	Silent by default, 6 events
`balanced`	SessionStart, UserPromptSubmit, SubagentStart, SubagentStop, Stop	5 events
`quiet`	Stop	1 event
`telemetry`	PostToolUse (Bash), Stop	Silent bookkeeping, 2 events

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

Remove only Token Optimizer’s managed hooks with:

TOKEN_OPTIMIZER_RUNTIME=codex python3 skills/token-optimizer/scripts/measure.py codex-install --uninstall
# For a project-scoped install, also pass --project "$PWD".