A multi-agent CLI that automatically saves Claude API costs by routing tasks to the cheapest adequate model, enforcing plan-before-build, and tracking every token spent.
Most people use Opus for everything — even simple tasks like extracting data or formatting text. That burns tokens fast. A simple task on Haiku costs 94% less than the same task on Opus.
This tool fixes that automatically.
Every task passes through a pipeline of agents:
Your task
↓
Router (Haiku) → picks cheapest model: Haiku / Sonnet / Opus
↓ complex tasks only
Karpathy Guard (Haiku) → surfaces assumptions + verifiable success criteria
↓ build tasks only
Planner (Sonnet) → creates a plan for your approval before any code runs
↓
Executor → streams response on the chosen model
↓
Memory Manager (Haiku) → extracts new facts, updates local brain
↓
Token Tracker → logs tokens + cost to logs/usage.json
| Agent | Model | Role |
|---|---|---|
| Router | Haiku | Keyword scan + LLM analysis to pick cheapest adequate model |
| Karpathy Guard | Haiku | Surfaces assumptions and verifiable success criteria before complex tasks |
| Planner | Sonnet | Creates an approved plan before any build task executes |
| Executor | Haiku / Sonnet / Opus | Streams the actual task on the routed model |
| Memory Manager | Haiku | Auto-extracts durable facts from each session into local brain |
| Token Tracker | — | Logs every API call with cost, shows daily/monthly dashboard |
The router picks the cheapest model that can handle the task:
| Complexity | Model | Triggered by |
|---|---|---|
| Simple | 💚 Haiku | list, what, show, explain, describe, review, compare, why, how |
| Medium | 💛 Sonnet | write, analyze, evaluate, draft, brainstorm, recommend |
| Complex | 🔴 Opus + Planner | build, code, implement, develop, debug, refactor, deploy |
The router applies a keyword scan first (free). If ambiguous, Haiku classifies — still far cheaper than defaulting to Opus.
| Task | Routed to | Actual cost | If Opus | Saved |
|---|---|---|---|---|
| List 5 benefits (simple) | Haiku | $0.002 | $0.010 | 80% |
| Analyze cost tradeoffs (medium) | Sonnet | $0.077 | $0.614 | 87% |
| Build fault detection agent (complex) | Opus | $0.275 | $0.275 | — |
At 100 tasks/day that's ~$27/month saved vs defaulting to Opus for everything.
1. Clone the repo
git clone https://github.com/Indianinnovation/Claude-Agentic-Token-Optimizer.git
cd Claude-Agentic-Token-Optimizer2. Install dependencies
pip install -r requirements.txt3. Add your API key
cp .env.example .env
# Edit .env and paste your Anthropic API key4. Run
python3 main.pypython3 main.py # interactive chat (default)
python3 main.py ask "task" # single-shot task
python3 main.py status # token usage dashboard
python3 main.py memory # view local brainCLI Flags:
python3 main.py --model opus # force a specific model for the session
python3 main.py --no-plan # skip the planning phase
python3 main.py --budget 200 # set monthly budget to $200
python3 main.py ask "task" -y # auto-approve all prompts (non-interactive)The router auto-selects the model. You can override at three levels:
Append use haiku, use sonnet, or use opus to any message:
You> explain how the FaultAgent works use opus
You> list the top 5 benefits use sonnet
!model sonnet # all tasks in this session use Sonnet
!model haiku # switch to Haiku
!model opus # switch to Opus
python3 main.py ask "explain this code" --model opus!status show token usage + cost dashboard
!memory view local brain (instructions + memory)
!newchat clear context, save session to memory, start fresh
!model <model> lock model for this session (haiku / sonnet / opus)
!quit end session (auto-saves memory)
The brain/ folder is your local memory system — never pushed to GitHub.
brain/instructions.md— global instructions injected into every prompt (conciseness, behaviour rules)brain/memory.md— auto-updated after each session with durable facts
Edit instructions.md to customise how Claude behaves across all tasks. The Memory Manager uses Haiku to extract and save only durable facts — not transient details.
├── main.py # CLI entry point + orchestration
├── optimizer/
│ ├── config.py # model IDs, pricing, routing keywords
│ ├── router.py # task complexity analyser + model router
│ ├── karpathy.py # Karpathy Guard: assumptions + success criteria
│ ├── planner.py # plan-before-build enforcement
│ ├── executor.py # streaming task executor
│ ├── memory_manager.py # local brain read/write
│ └── token_tracker.py # usage logging + cost dashboard
├── brain/
│ └── instructions.md # your Claude behaviour instructions
├── logs/ # usage.json written here at runtime
├── .env.example # API key template
├── .gitignore # excludes .env, memory.md, usage.json
└── requirements.txt
| Variable | Required | Default | Description |
|---|---|---|---|
ANTHROPIC_API_KEY |
Yes | — | Your Anthropic API key |
CLAUDE_MONTHLY_BUDGET |
No | 100.0 |
Monthly spend limit in USD for budget warnings |
Based on Generative AI cost best practices:
| Strategy | How this tool implements it |
|---|---|
| Token usage | Routes simple tasks to Haiku (94% cheaper input rate) |
| Model selection | Auto-picks cheapest model per task; never defaults to Opus |
| Prompt caching | brain/instructions.md acts as a reusable static context |
| Response control | Planner caps scope before build tasks run |
| Continuous monitoring | !status dashboard + budget alerts at 75% and 90% |
| Context management | Warns at 20 msgs, alerts at 35 msgs to start new chats |
| Memory efficiency | Only relevant brain context injected per prompt |
The token optimization framework is also available as a standalone Claude Code skill — no API key or Python needed.
bash <(curl -fsSL https://raw.githubusercontent.com/Indianinnovation/Claude-Agentic-Token-Optimizer/main/install-skill.sh)mkdir -p ~/.claude/skills/token-optimizer
curl -fsSL https://raw.githubusercontent.com/Indianinnovation/Claude-Agentic-Token-Optimizer/main/skills/token-optimizer/SKILL.md \
-o ~/.claude/skills/token-optimizer/SKILL.mdIn any Claude Code session:
/token-optimizer
Claude will then classify your task, recommend the cheapest model, and enforce plan-before-build for complex tasks — all within the conversation.
| Step | Action |
|---|---|
| 1 | Classifies task as simple / medium / complex |
| 2 | Recommends Haiku / Sonnet / Opus accordingly |
| 3 | For complex tasks: states assumptions + success criteria before any code |
| 4 | Controls response length to avoid runaway output tokens |
| 5 | Flags when context is too long (20+ messages) |
| 6 | Reports estimated cost at end of complex tasks |
- Andrej Karpathy's LLM coding guidelines
- "Never Hit Your Claude Usage Limit Again" — token optimisation strategies
MIT