Building with mini, Part 0: Why a Minimalist Orchestrator for Claude Code

A developer created a minimalist CLI tool called "mini" to reduce token consumption when using Claude Code across multiple sessions, keeping state thin with only a `project.md` and `state.json` file. The tool sends Claude only 600-1000 tokens per phase and handles state operations through tested TypeScript rather than relying on Claude itself. The project is available as open source (MIT) via `npx mini-orchestrator install-commands`.

In my previous article https://dev.to/stkremen/how-i-stopped-burning-tokens-in-claude-code-2okd 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 https://github.com/czsoftcode/mini-orchestrator Next up: Part 1 — init. I'll see you there. 🛠️