Health and diagnostics

When something looks off, the diagnostic commands tell you what state Token Optimizer is actually in. Some commands change local state. Use the documented dry-run flag where available; kill-stale, repair, and cleanup verbs are not all dry-run by default.

Doctor: verify the install

doctor is the first command to run when anything seems wrong. It verifies every component is wired correctly and reports pass, warn, or fail per component: hooks, status line, smart compaction, dashboard daemon, and quality bar.

python3 measure.py doctor
python3 measure.py doctor --json

doctor delegates on Codex. Other foreign runtimes may return a safe platform notice for this Claude-targeting verb; use their explicit adapter doctors below.

Platform	Command
Claude Code (CLI and VS Code)	python3 measure.py doctor
Codex	TOKEN_OPTIMIZER_RUNTIME=codex python3 measure.py codex-doctor --project "$PWD"
GitHub Copilot	TOKEN_OPTIMIZER_RUNTIME=copilot python3 measure.py copilot-doctor
Hermes	TOKEN_OPTIMIZER_RUNTIME=hermes python3 measure.py hermes-doctor
Cursor	TOKEN_OPTIMIZER_RUNTIME=cursor python3 measure.py cursor-doctor --probe
Grok Build	TOKEN_OPTIMIZER_RUNTIME=grok python3 measure.py grok-doctor --probe
Pi	/token-optimizer doctor inside Pi
Google Antigravity	TOKEN_OPTIMIZER_RUNTIME=antigravity python3 measure.py antigravity-doctor
OpenClaw	npx token-optimizer doctor --json
OpenCode	token_status inside OpenCode

codex-doctor is healthy at 0 FAIL. copilot-doctor names which data source is active for each surface and shows capability freshness for the installed Copilot CLI version. hermes-doctor checks home resolution, plugin presence, required files, declared hooks, a bridge smoke test, the activation entry, state database readability, and dashboard port availability. antigravity-doctor checks home resolution, the agy binary, plugin presence, the consent record, conversation-store readability (including undecodable-row counts), and dashboard port availability.

Session health

health checks the session that is running right now: fill level, quality, and which hooks are active.

python3 measure.py health

health-selfcheck runs a self-test of the health collection system to confirm every component can be read without error. Use it when health itself behaves unexpectedly.

python3 measure.py health-selfcheck

ensure-health is the self-healer that runs automatically on SessionStart. You can run it by hand to force a repair pass: it reinstalls a missing status line (unless opted out) and fixes drifted hook wiring.

python3 measure.py ensure-health

Drift, snapshot, and baseline

Drift detection answers “what changed since last time.” It compares the current setup against the last saved snapshot and reports differences in skill count, MCP servers, CLAUDE.md size, and token totals.

python3 measure.py drift
python3 measure.py drift --json

The snapshot workflow captures a named before-and-after pair so you can prove an optimization worked.

python3 measure.py snapshot before   # capture current state as "before"
# ... make changes ...
python3 measure.py snapshot after    # capture current state as "after"
python3 measure.py compare           # show the delta

set-baseline --opus N records the pre-TO Opus share used by savings comparisons, not the drift snapshot. Use snapshot/drift for setup changes; pin-baseline builds the frozen anchor to completion.

python3 measure.py set-baseline --opus 0.95  # example: measured pre-TO Opus share

Git context

git-context analyzes the current git state (modified files, branch) and suggests the files most relevant to the task at hand.

python3 measure.py git-context
python3 measure.py git-context --json

Cleaning up

kill-stale ends terminal sessions (processes positively identified as a CLI attached to a terminal) that have been running longer than a threshold. Sessions hosted by the desktop app, an IDE or the SDK, and sessions whose identity could not be verified, are never ended. The default threshold is 12 hours. It is dry-run capable so you can see what would be killed first.

python3 measure.py kill-stale --dry-run
python3 measure.py kill-stale --hours 6

On macOS and Linux an interactive session whose terminal died (no controlling terminal, parent is launchd/init/systemd --user, readable argv, not an Electron app) is listed as ORPHAN (“terminal gone; started 3d 4h ago”). kill-stale never ends orphans by default; it prints how many it left alone and the exact command. Add --include-orphans (with the same --hours and --dry-run) to end them; each one is re-verified right before it is signalled. Automations started by launchd or systemd normally carry -p/--print and are never treated as orphans. Windows has no ORPHAN class.

python3 measure.py kill-stale --include-orphans --dry-run
python3 measure.py kill-stale --include-orphans --hours 24

plugin-cleanup removes stale or orphaned plugin cache entries from the plugin cache directory.

python3 measure.py plugin-cleanup --dry-run
python3 measure.py plugin-cleanup

Dashboard diagnostics

daemon-status checks whether the dashboard daemon is genuinely running, with identity verification rather than a bare TCP probe. It returns one of DAEMON_RUNNING, DAEMON_NOT_RUNNING, or DAEMON_FOREIGN (a different process holds the port).

python3 measure.py daemon-status

dashboard-diagnose validates the JSON data shape that the engine injects into the dashboard HTML. Run it when a dashboard tab renders empty: it diagnoses the silent schema mismatch behind the blank panel.

python3 measure.py dashboard-diagnose

Security self-assessment

security-report runs an enterprise-style self-assessment covering credential patterns, data locality, hook permissions, and OWASP-style checks.

python3 measure.py security-report
python3 measure.py security-report --json

For the underlying architecture this report checks against (loopback-only dashboard, token-gated POST endpoints, 0o700/0o600 permissions, credential redaction), see Your data and privacy.

Quick triage order

1. doctor to confirm everything is installed.
2. health to read the live session state.
3. drift to see what changed since the last good state.
4. daemon-status and dashboard-diagnose if the dashboard is misbehaving.
5. kill-stale and plugin-cleanup to clear residue.
6. security-report for a periodic posture check.