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

> Source: <https://dev.to/stkremen/building-with-mini-part-0-why-a-minimalist-orchestrator-for-claude-code-jpb>
> Published: 2026-06-03 11:00:00+00:00

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