---

What it does

Point TokenOptimizer at a project and it:

• Indexes the codebase with Graphify so Claude Code can query a knowledge graph instead of grepping blind.
• Installs matching skills automatically via the app's own skill catalog + Claude Code plugin wiring (autoskills is updated/uninstalled as a legacy dependency when present).
• Launches Claude Code with real token-saving tooling wired in on first run: Caveman for terser model output, RTK for compressed terminal/tool output, plus claude-mem, headroom, and a few other companion plugins.
• Falls back automatically when Claude Code itself is unavailable - Antigravity, then OpenCode Go, then a locally-run model via the Unsloth CLI - so a rate limit or an outage doesn't stop your session.
• Adds Groq and Codex/Cursor as manual, one-click alternatives when you want to switch deliberately instead of automatically.
• Serves frontier MoE models locally via FreeToken (FreeToken (local MoE) provider): the desktop engine from flashml.ai speaks Anthropic's API natively on 127.0.0.1:1919, so Claude Code can run against a local Qwen3.6-35B-A3B / GLM-5.2-class model with no proxy or translation layer. See freetoken_local/README.md for the companion Python handler and live self-test.
• Integrates Hermes Agent (Hermes Agent provider) as an encompassing peer layer: launches real hermes chat sessions in your project, and scripts/Setup-HermesIntegration.ps1 points Hermes' own custom-endpoint config at TokenOptimizer-managed local engines - so Hermes sessions ride the same local MoE engine through one ecosystem. See docs/ARCHITECTURE.md for the full design.
• Runs sessions inside OpenSandbox containers (mandatory) - the preflight gate checks Docker Desktop and starts the opensandbox-server for you, so every session is isolated with its companion tooling baked into the image. Docker Desktop is required.

Everything above is one Avalonia desktop app (app/). A companion VS Code extension gives you the same launcher and a live dashboard from inside the editor.

Install

Download the latest TokenOptimizer.msi from Releases and run it. No PowerShell, no manual dependency installs - the installer bundles the app itself and the VS Code extension, with Start Menu shortcuts from the WiX-built MSI.

Build from source

Prerequisites:

• .NET 10 SDK - dotnet.microsoft.com
• Node.js + npm - only needed to build the VS Code extension or the MSI, not for dotnet build
• Docker Desktop - needed at runtime: sessions run inside OpenSandbox containers, so the app's preflight gate expects a running Docker engine (docker.com)

cd app
dotnet build TokenOptimizer.slnx
dotnet run --project src\TokenOptimizer.App

Run the test suite:

dotnet test TokenOptimizer.slnx

To build the installable TokenOptimizer.msi yourself (what CI/Releases produce):

# one-time setup
dotnet tool install --global wix --version 5.0.2
cd app\installer
wix extension add WixToolset.UI.wixext/5.0.2 WixToolset.Util.wixext/5.0.2

# build the MSI
.\build-installer.ps1

WiX is pinned to 5.0.2 on purpose - v6+ requires a paid-tier EULA for some usage, and 5.0.2 predates that and is free. The output lands at app\installer\TokenOptimizer.msi.

How the pieces fit together

Fallback chain

Automatic, no setup beyond saving credentials once:

1. Claude Code - primary, always tried first
2. Antigravity - Google's IDE, if installed and its credential is registered
3. OpenCode Go - a low-cost gateway to open coding models, if its API key is saved
4. Local model - the best-scoring Unsloth-served model on your own machine

Manual only - reachable by picking them directly, since they're separate products rather than swappable backends:

• Groq - fast inference API, bridged to Claude Code's Messages schema locally
• Codex / Cursor - session context and skills bundled into a handoff file, referenced from AGENTS.md so the receiving tool sees it on open

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for the development setup, test commands, and PR checklist, and CODE_OF_CONDUCT.md for community expectations.

License

MIT - see LICENSE. A rough example EULA for a compiled-binary distribution (not required for the MIT-licensed source itself) lives at docs/EULA-example.md.

---

Legacy: the PowerShell launcher

LLM-TokenOptimizer.ps1 is the original self-bootstrapping launcher that the C# app replaced in v6.0. It still works and is kept for reference, but new users should use the MSI/app path above instead. Full behavior, flags, and troubleshooting for it are documented in AUDIT.md, which covers v5.0 through v5.5 and predates the v6.0 app - treat it as project history, not current-state documentation.

Before first use:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
.\LLM-TokenOptimizer.ps1

Quick reference for the flags most people actually reach for:

For the full flag list, run Get-Help .\LLM-TokenOptimizer.ps1 -Full, or see AUDIT.md for historical documentation (predates v6.0, may not reflect every current flag).