CLI & Slash Commands
Relevant source files
The following files were used as context for generating this wiki page:
CLI and Slash Commands form the operational interface for the Token Optimizer project, enabling users to audit, analyze, and optimize the token usage of their AI agents (specifically Claude Code and Codex). These commands are executed via a central orchestration script, measure.py, which handles environment detection, data collection, and integration with the underlying AI models.
The system is designed to provide both automated "Slash" style commands within a chat interface and direct CLI execution for advanced management and analytics. Key functionalities include context window waste identification, automated compaction management, and session health auditing.
Command Architecture and Execution Flow
The architecture relies on a runtime detection layer that gates execution based on the environment (Claude, Codex, OpenCode, or Copilot). Once the environment is validated, commands interact with a coordination path (COORD_PATH) to store audit results and analysis files.
Runtime Detection Logic
Before any command execution, the system resolves the path to measure.py and executes a runtime gate. This prevents unauthorized mutations to configuration paths in unsupported environments.
The system scans multiple directories including ~/.claude/skills, ~/.claude/plugins/cache, and ~/.codex/skills to find the newest version of the measurement script.
Sources: skills/token-optimizer/SKILL.md:27-101, skills/token-coach/SKILL.md:22-68
Core Slash & CLI Commands
The system exposes several primary commands used during different phases of the optimization lifecycle.
Optimization and Auditing
These commands manage the end-to-end audit and implementation flow.
| Command | Type | Description |
|---|---|---|
/token-optimizer | Slash | Orchestrates the full 5-phase audit and implementation process. |
measure.py report | CLI | Performs the authoritative runtime gate and reports environment status. |
measure.py collect | CLI | Collects session usage data; typically triggered by the SessionEnd hook. |
measure.py dashboard | CLI | Generates a visual summary of optimization findings and URL presentation logic. |
measure.py quality | CLI | Analyzes session JSONL to score context relevance and identify rot. |
Sources: skills/token-optimizer/SKILL.md:12-18, skills/token-optimizer/SKILL.md:245-247, skills/token-optimizer/references/optimization-checklist.md:599-605, skills/token-coach/SKILL.md:89-94
Coaching and Health
Commands focused on proactive session management and architectural advice.
| Command | Type | Description |
|---|---|---|
/token-coach | Slash | Interactive coaching for building token-efficient projects. |
measure.py coach --json | CLI | Retrieves historical usage trends, cost summaries, and pattern detection data. |
/context | Slash | Built-in command to display current context window fill levels. |
/cost | Slash | Displays current session spending and thinking token breakdown. |
Sources: skills/token-coach/SKILL.md:1-12, skills/token-coach/SKILL.md:74-87, skills/token-optimizer/references/optimization-checklist.md:12-25
System Management and Automation
Advanced commands handle background scheduling, session continuity, and system hooks.
Keep-Warm & Scheduling
Used to maintain the prompt cache during pauses in API-key-billed sessions.
keepwarm-consent-status: Returns JSON indicating if the user should be asked to enable the feature.keepwarm-backfill: Projections of potential savings based on the last 30 days of history.keepwarm-scheduler status: Checks the state of the task scheduler (macOS specific).keepwarm-tick --dry-run: Simulates the next cache ping decision.
Sources: skills/token-optimizer/SKILL.md:118-150, skills/token-coach/SKILL.md:104-120
Session Continuity (Cold-Resume-Lean)
Enables inexpensive resumption of cold sessions without using the heavy --resume flag.
resume-lean: Lists available cold sessions for restoration.resume-lean <id> --print: Emits a lean context block for injection into a new session.
Sources: skills/token-optimizer/SKILL.md:280-297
Smart Compaction and Hooks
Automation for preserving state during context window overflows.
setup-smart-compact: InstallsPreCompactandSessionStarthooks to capture and restore structured state.check-hook: Verifies the installation status of system hooks.setup-hook: Installs lifecycle hooks likemeasure.py collect.
Sources: skills/token-optimizer/references/implementation-playbook.md:154-165, skills/token-optimizer/references/optimization-checklist.md:544-555
Execution Sequence Diagram
The following diagram illustrates how a slash command like /token-optimizer dispatches parallel agents and synthesizes results.
Summary
The CLI and Slash commands within Token Optimizer provide a comprehensive suite for measuring and reducing AI context overhead. By combining authoritative environment gating via measure.py with parallel auditing agents and automated hooks, the system ensures that AI sessions remain high-quality and cost-effective. Key features like resume-lean and Smart Compaction ensure continuity, while commands like /token-coach provide architectural guidance for developers.
Sources: skills/token-optimizer/SKILL.md, skills/token-coach/SKILL.md, skills/token-optimizer/references/optimization-checklist.md