{"slug": "building-with-mini-part-0-why-a-minimalist-orchestrator-for-claude-code", "title": "Building with mini, Part 0: Why a Minimalist Orchestrator for Claude Code", "summary": "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`.", "body_md": "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.\n\nSo 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.\n\nEverything in mini comes from a single principle:\n\nKeep minimal state, and send Claude only the essentials.\n\nMost orchestration tools fail the opposite way — they accumulate documentation (`RESEARCH.md`\n\n, `PLAN.md`\n\n, `VERIFICATION.md`\n\n, …) and re-read it into context at every step. The bookkeeping ends up costing more tokens than the actual work.\n\nmini keeps state thin:\n\n`project.md`\n\n`state.json`\n\nWhen 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.\n\nThe 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`\n\n. The state can never break from a hallucination. That's the part I never trusted in purely prompt-based setups.\n\nHere's the plan. I'll fill in each link as the posts go live — follow the series if you want them as they land.\n\n`init`\n\n`import-gsd`\n\n, `audit`\n\n, `map`\n\n`todo`\n\n`next → plan → do → done`\n\n`discuss`\n\nand `verify`\n\n`auto`\n\nand `stop`\n\n`status`\n\n, `undo`\n\n, `model`\n\n`changelog`\n\n, `doctor`\n\nmini is free and open source (MIT). If you want to try it before the series unfolds:\n\n```\ncd your-project\nnpx mini-orchestrator install-commands\n```\n\nRepo with a demo GIF: [github.com/czsoftcode/mini-orchestrator](https://github.com/czsoftcode/mini-orchestrator)\n\nNext up: Part 1 — init. I'll see you there. 🛠️", "url": "https://wpnews.pro/news/building-with-mini-part-0-why-a-minimalist-orchestrator-for-claude-code", "canonical_source": "https://dev.to/stkremen/building-with-mini-part-0-why-a-minimalist-orchestrator-for-claude-code-jpb", "published_at": "2026-06-03 11:00:00+00:00", "updated_at": "2026-06-03 11:13:08.025628+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "large-language-models", "ai-products"], "entities": ["Claude Code", "mini", "TypeScript"], "alternates": {"html": "https://wpnews.pro/news/building-with-mini-part-0-why-a-minimalist-orchestrator-for-claude-code", "markdown": "https://wpnews.pro/news/building-with-mini-part-0-why-a-minimalist-orchestrator-for-claude-code.md", "text": "https://wpnews.pro/news/building-with-mini-part-0-why-a-minimalist-orchestrator-for-claude-code.txt", "jsonld": "https://wpnews.pro/news/building-with-mini-part-0-why-a-minimalist-orchestrator-for-claude-code.jsonld"}}