In my previous article I described the wall I kept hitting with Claude Code: keeping a project on track across dozens of sessions burns an absurd amount of tokens. The fix I landed on was a small CLI called mini — and a few people asked me to go deeper than one article allows.
So this is the start of a series. One post per part, each focused on a single piece of the tool, with a running example you can follow along. This part is the map: the philosophy behind mini, and where the series is headed.
Everything in mini comes from a single principle:
Keep minimal state, and send Claude only the essentials.
Most orchestration tools fail the opposite way — they accumulate documentation (RESEARCH.md
, PLAN.md
, VERIFICATION.md
, …) and re-read it into context at every step. The bookkeeping ends up costing more tokens than the actual work.
mini keeps state thin:
project.md
state.json
When I work a phase, Claude typically gets ~600–1000 tokens. No history of old phases, no old plans. If it needs to understand the code, it reads the files itself — cheaper than stuffing the whole repo into context up front.
The second principle is just as important: state operations are done by non-trivially tested TypeScript, not by Claude. Claude does the agentic work in a session; moving the phase, writing the report, closing things out — that's all mini ... --apply
. The state can never break from a hallucination. That's the part I never trusted in purely prompt-based setups.
Here's the plan. I'll fill in each link as the posts go live — follow the series if you want them as they land.
init
import-gsd
, audit
, map
todo
next → plan → do → done
discuss
and verify
auto
and stop
status
, undo
, model
changelog
, doctor
mini is free and open source (MIT). If you want to try it before the series unfolds:
cd your-project
npx mini-orchestrator install-commands
Repo with a demo GIF: github.com/czsoftcode/mini-orchestrator
Next up: Part 1 — init. I'll see you there. 🛠️