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

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.

The one idea behind mini

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 — one page: what you're building, for whom, the constraints.
• state.json — a lightweight header: phase index, statuses, models. Per-phase detail lives separately and loads only when needed.

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 other half: state lives in tested code

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.

What the series will cover

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.

1. Initializing a project — init (coming soon) Starting from scratch and understanding what state mini actually keeps.
2. Onboarding an existing project — import-gsd, audit, map (coming soon) Dropping mini into a project that's already running.
3. Capturing ideas — todo (coming soon) A backlog for things that aren't phases yet.
4. The main loop — next → plan → do → done (coming soon) The heart of mini: propose, break down, build, close.
5. When you need to think — discuss and verify (coming soon) The two human checkpoints around the loop.
6. Autonomous mode — auto and stop (coming soon) Running phases back to back, with a clean way to stop.
7. State commands — status, undo, model (coming soon) Seeing where you are, undoing a step, controlling cost.
8. Health commands — changelog, doctor (coming soon) Project diagnostics and change history.

Follow along

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. 🛠️