Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
The Installation & Setup process for Token Optimizer provides a robust framework for deploying token-efficiency tools across multiple AI runtimes, including Claude Code, Codex, OpenCode, and GitHub Copilot. The system is designed to be idempotent, ensuring that re-running installation scripts safely updates the environment without corrupting existing configurations.
The core installation logic resides in a central shell script that handles prerequisite verification, integrity checks, and environment-specific linking. Once installed, the system utilizes a specialized script, measure.py, to resolve paths and manage hooks across different platforms.
Sources: install.sh:1-25, skills/token-optimizer/SKILL.md:65-85
Core Installation Architecture
The primary installation method is a one-command bash script. It orchestrates the setup by cloning the repository, verifying checksums, and creating symlinks within the AI tool's internal directory structure.
Prerequisite Verification
The installer enforces strict version requirements to ensure compatibility with modern AI toolhooks and Python features.
| Prerequisite | Requirement | Purpose |
|---|---|---|
| Python | 3.9+ | Running measurement and hook scripts |
| Git | Latest | Repository management and sparse checkouts |
| curl | Latest | Fetching out-of-band checksums for integrity |
| Runtime Home | ~/.claude or similar | Destination for skills and settings |
Sources: install.sh:426-455
Installation Flow
The following diagram illustrates the high-level logic used by install.sh to deploy the optimizer.
The installer uses sparse checkouts to minimize disk footprint, pulling only necessary skill and hook directories.
Sources: install.sh:558-575, install.sh:712-740
Multi-Runtime Configuration
Token Optimizer detects and configures itself differently based on the active environment. The measure.py script acts as the authoritative resolver for these settings.
Runtime Detection Logic
Before execution, the system checks environment variables to determine the target platform. This prevents Claude-specific logic from running in OpenCode or Copilot environments.
Special Runtime Procedures
- OpenCode: Uses
bunas the runtime. The installer builds a TypeScript plugin bundle and places it in~/.config/opencode/plugins/. - Codex: Requires
TOKEN_OPTIMIZER_RUNTIME=codex. Setup includes installing "balanced" hooks viacodex-installto manage subagent sprawl and memory densification. - GitHub Copilot: Installs hooks into
~/.copilot/hooks/token-optimizer.jsonand supports VS Code debug log integration for credit cost tracking.
Sources: install.sh:59-105, skills/token-optimizer/references/codex-workflow.md:65-80, install.sh:379-410
Hook & Quality Bar Setup
A critical part of the setup is the installation of lifecycle hooks that monitor token usage in real-time.
Automation Hooks
The system attempts to automatically merge hooks into the AI tool's settings.json.
- PreCompact: Guides the AI on what context to preserve during automatic compaction.
- PostToolUse: Can trigger auto-formatters to save output tokens on style explanations.
- SessionEnd: Runs
measure.py collectto record session data for the dashboard.
Sources: skills/token-optimizer/references/implementation-playbook.md:130-155, install.sh:767-785
The Quality Bar
The "Quality Bar" provides a real-time status line (ContextQ score) that updates every ~2 minutes. It is installed via measure.py setup-quality-bar during the final phase of install.sh.
Sources: install.sh:755-763
WSL Integrity and Path Recovery
A common installation issue occurs when running install.sh as root under WSL (Windows Subsystem for Linux). In this scenario, the installer would default to /root/.claude, whereas the Windows-native AI CLI expects files in the user's Windows profile.
The installer includes a specialized recovery function, _recover_home_from_windows_env, which:
- Uses PowerShell to query the Windows registry for environment variables like
COPILOT_HOMEorCLAUDE_CONFIG_DIR. - Translates Windows drive paths (e.g.,
C:\Users\...) to WSL mount points (e.g.,/mnt/c/Users/...). - Exports these recovered paths so the installation lands in the correct cross-filesystem location.
Sources: install.sh:220-280, install.sh:305-345
Conclusion
The Installation & Setup of Token Optimizer is a highly automated process that prioritizes environment awareness and file integrity. By leveraging sparse checkouts and out-of-band checksum verification, it ensures a secure and lightweight footprint. The multi-runtime detection logic ensures that whether a developer is using Claude Code, Codex, or OpenCode, the appropriate measurement hooks and optimization strategies are correctly applied to the specific host environment.