#mini-orchestrator
Português

← Todos os posts

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

In my 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.

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

Next up: Part 1 — init. I'll see you there. 🛠️