MoAI-ADK

A verification-driven agent orchestration harness — the structure that makes Claude Code's code trustworthy

English · 한국어 · 日本語 · 中文

Official Documentation · Book: Practical Agentic Coding with Claude Code · Discord

---

"The model is a stochastic worker moving token by token. It cannot remember, turn to turn, what it used this turn and how much, whether the result is good, or how far the last session got. A harness enforces all three from the outside."

---

What's New in v3.1 — Kanban Mode

v3.1 ships on August 15, Liberation Day in Korea. The intent: release work from the old shape of a single session bound to one context limit. The limit itself does not disappear — what actually changes is written down below.

A session holds one context window, and a long SPEC fills it. Everything that comes after carries everything that came before: the plan you no longer need is still in the window while you review, and the review is still there while you write docs. The usual escape is /clear, which throws away the thread along with the ballast.

Kanban Mode splits one unit of work across four terminals instead of one. A lead session drives the chain; three companion sessions each own a single column — plan, run, sync — and carry only that column's context. Review is not a separate column: the sync gate absorbs it, running the review lenses itself to reach the verdict. Nothing is uncapped: each session still has its own limit. What changes is that no session carries three phases' worth of history, so the same budget goes considerably further, and a finished phase is cleared without losing the card.

Each column can run a different backend and effort level. The run above puts Plan on Opus 5 at high effort, Run on GLM 5.2 at xhigh, and Sync on GLM 5.2 — the depth of reasoning a column needs is not the same in every column.

Getting started

moai cc -k                    # lead — announces a run-id, seeds the chain
moai cc -k --name plan        # companion, in its own terminal
moai cc -k --name run
moai cc -k --name sync

Companion sessions are launched by hand, one per terminal — a session never spawns a peer. Companions are named by their bare role: the run-id stays the lead session's identifier and never rides a companion name; a second live session claiming the same role takes the next free number. Swap moai cc for moai glm on any column to put just that column on the GLM backend.

Which backend goes where

When you open a kanban run, the bootstrap notice carries a default recommendation — token availability first: lead on moai glm -k, plan on moai cc -k --name plan, run on moai glm -k --name run, sync on moai cc -k --name sync. The reasoning is the kind of thinking each lane needs. Plan and sync turn on judgment and review, so they sit on Claude; run is implementation-heavy, so GLM keeps its cost down. The lead is not the seat that renders verdicts — it watches the queue and moves cards — so GLM, cheap to keep waiting, fits it. When a Claude verdict is needed under a GLM lead, escape through a session named judge — the only route by which the GLM lead uses Claude. When one account starts hitting 429s, spreading lanes across accounts is the workable move. This mix is only the default — a different combination, or unifying every session on one backend, is equally fine.

Factory Mode — many cards at once across N lanes

-f opens a factory lead, Kanban's second form. Where a kanban card hops between columns, a factory card goes whole to one lane, and that lane carries it through plan → run → sync serially in-session, each phase spawned as Agent() subagents. Lanes are labelled lane-1 … lane-N.

moai cc -f                    # lead — one lane (lane-1) by default
moai cc -f 4                  # lead — four lanes
moai cc -f lane-1             # a lane, in its own terminal
moai glm -f lane-3            # …and one lane on the GLM backend

Grow a run one lane at a time with moai cc -f lane-<n>. That form already names the lane, so passing --name/-n alongside it is an error. A number is skipped only while a live session holds it — a dead lane's number is released and reused. Which numbers are held is recorded in .moai/state/factory/workers.json, and that is where stale claims get cleared. A lane runs up to 10 concurrent Agent() subagents, and write-capable spawns are isolated in their own worktree. Never bring every lane up at once — start the first, confirm it is actually producing output, then activate the rest. Cards are never split across lanes. -k still drives the three-role kanban chain; one launch takes one entry token, so -k with -f is an error, and moai cg refuses factory mode.

Details: Kanban mode — Factory Mode

The board has five columns, backlog → plan → run → sync → done. backlog has no owning session by design, so work enters the board only when you put it there:

/moai todo "fix the stale rename hint"   # append a card
/moai todo                               # list the queue

Two rules keep the board honest. The lead advances a card only on evidence it read from the card's progress.md — never on a companion's reply, because a reply is a claim and inter-session delivery is not guaranteed. And when a phase ends, the lead asks for that session to be /clear-ed, since /clear is user-typed and cannot be sent as an instruction.

Words the four sessions share

The recurring vocabulary of the kanban docs, gathered into one picture. A column is a stage of the board; a lane is the pair of a session and its worktree that carries one card through those stages to the end — the difference between a stop and a route.

Operator ── /moai todo ──▶ backlog ─▶ plan ─▶ run ─▶ sync ─▶ done
                          (the lead advances a card only on evidence it read)

Lane — card t0:  run session + worktree t0      ┐ the two flows share one board,
Lane — card t1:  run session + worktree t1      ┘ run side by side, never mix

Term	One-line definition
card	One unit of work. Enters via /moai todo, addressed by a short id
column	One stage of the board — five columns in fixed order
backlog	The entrance queue. No owning session, so only a human can add work
lane	The session+worktree pair that carries one card to the end. One parallel work stream
lead	The coordinating session. Advances cards only on evidence it read; never writes code itself
companion	The session seated in a column doing the work. Launched by hand, one per terminal
run-id	Short identifier the lead announces at start. It names the lead session; companions never carry it
worktree	The card's isolated checkout. The directory carries the card id; the branch carries what the card did (WT-<slug>). One carries the card from run through sync
dispatch	The instruction the lead sends a companion — a pointer to the work, never a copy

Full glossary with definitions and examples: Kanban board terms

Cards also differ in which columns they pass through, by shape. As a card leaves backlog, the lead classifies it into one of the three Card Classes and names the class in the dispatch.

Class	Shape	Shortcut
A — direct close	one file · one line, no design judgment, regression caught by CI	one session carries it whole to the PR (plan skipped)
B — defect, cause unknown	clearly broken, but the cause is not yet established	run → sync (no plan, no SPEC)
C — design change	carries a decision or spans subsystems	all three columns

Class A is admitted on checked evidence, not assertion — a card that cannot cite a diff measured to one file and green CI on the head that will merge is not Class A. Class B skips only plan; the sync gate's review still runs, and the cause-establishing evidence (reproduction command and its output) is left in the card's progress record.

Details: Kanban Mode — card classes

Watching the board

moai web serves a local console. The Kanban screen shows the kanban chain alongside the SPEC pipeline, plus Overview, Specs, Monitor, Settings, and Todo screens.

Full guide: Kanban Mode · manager-lead Lead Coordinator · /moai todo

What v3.1.1 adds

Kanban Mode aside, here is what else landed in v3.1.1. Each one is covered in full in its own section further down.

Home directory hygiene. The longer you use it, the more leftovers from past runs pile up in ~/.moai. moai clean --home clears them out, staying inside an allowlist — it is a dry run by default, so it shows you what would go before anything goes, and actual deletion needs --force. How old something has to be before it is swept is set by state.home_retention_days (30 days by default, 0 turns it off). To see how far the directory has grown right now, moai doctor reports it under Home Disk Usage. The home path itself can be moved with the MOAI_HOME environment variable — it takes absolute paths only. Only Go processes read it, though: move the path and the statusline and the shell hooks still look under $HOME/.moai. Shell-side credentials like .env.glm and the statusline's data stay behind, and your state quietly splits in two.

Cross-session messaging settings. Whether a message from another Claude Code session arrives directly, waits for approval, or is refused outright is decided in crosssession.yaml. The switch that requires approval before a message leaves this machine lives there too.

Statusline GitLab support. statusline.forge picks whether open work is counted on GitHub or on GitLab. Left empty, it decides from the origin remote's host.

A bare /loop becomes the kanban foreman. Typing /loop with no arguments starts a cycle that watches the backlog queue, dispatches the next card the operator has already marked picked to an isolated worker, confirms completion from evidence it read rather than from a claim, and reports. Nobody is watching that seat, so both putting cards in the queue and picking them stay the operator's job — the foreman never picks, it only carries.

---

Why moai-adk?

The age of agents writing code has arrived, but you cannot take an agent's output on faith. Whether "the tests passed" is the result of actually running the tests or just the agent's guess has been the central problem from the start. moai-adk begins exactly there — it bans unverified completion claims at the system level and binds every completion claim to the command actually run and its output as evidence.

moai-adk is a harness that wraps Claude Code from the outside. It does not replace Claude Code; it takes over, in structure, the parts you used to manage by hand — which model to use, how deeply to reason, how to verify results, how to resume when a session breaks, how to keep parallel runs from stepping on each other. Verification integrity, the SPEC lifecycle, autonomous execution with real boundaries, a living codebase navigator, a self-improvement loop, and parallel-safe structure. These six form the identity of moai-adk.

This identity organizes into three keys: cost (tokenomics — the same quality for fewer tokens), self-improvement (agentic loop engineering — turning observation into rules so the harness gets better as it runs), and quality control (the SPEC lifecycle, TRUST 5 gates, and isolation that prevents rework). No one of them suffices alone — below, why each needs the others.

Eight differentiators

Differentiator	What it means
No false verification	A claim that "tests pass" is always bound to the command actually run and its output. The system forbids presenting an unrun check as a success — verification-claim integrity is bound into every agent and orchestrator surface.
Autonomy with real boundaries	Declare a completion condition with /moai goal and the session works on its own until it holds. Four hard boundaries are attached — a turn limit (default 30), a stagnation guard, a wall-clock budget, and pre-approval gates — so it cannot fall into an infinite loop.
Parallel-safe	Every SPEC gets its own working tree, a branch-state guard blocks accidental branch switches in the primary checkout, and the gap against the remote is checked before spawning write agents. Two write-capable agents never run at the same time.
Long-horizon continuity	Work survives /clear. Progress stays in progress.md, handoff messages in memory, routing decisions in decision memory. The next session starts from what the last one learned, not from bare ground.
Cost-efficient	Models and reasoning depth are assigned declaratively, matched to work phase and SPEC size. CG mode (Claude leader + GLM workers) cuts 60–70% of cost on implementation-heavy work. Prompt caches are reused and long output is spilled to disk to keep the context light.
Equal support for 16 programming languages	Go, Python, TypeScript, JavaScript, Rust, Java, Kotlin, C#, Ruby, PHP, Elixir, C++, Scala, R, Flutter, Swift — sixteen programming languages handled as one set via marker-based auto-detection. None receives preferential treatment.
Self-improving	Recurring failure patterns observed in the wild rise as proposed rule changes. Nothing is applied silently — approval comes first. Routing decisions and gate evidence accumulate in decision memory as material for the next run.
Native-language friendly	Korean, Japanese, Chinese, and English locales are maintained in the same PR, translationese is banned, and each language gets its own native prose. Users are never forced into English.

What's different

	Claude Code alone	Typical harness	moai-adk
Evidence binding of completion claims	You check by hand	Usually absent	Enforced by the system (5-section evidence report format)
SPEC lifecycle	None	Limited	plan→run→sync 3-phase + Tier S/M/L
Hard boundaries on autonomous loops	N/A	Usually a turn cap only	Turn limit + stagnation guard + wall clock + approval gate
Parallel work isolation	Manual	Limited	worktree + branch guard + pre-spawn sync check
Session continuity	Broken by /clear	Limited	handoff + memory + progress files
Equal treatment of 16 programming languages	N/A	N/A	marker auto-detection + per-language toolchains
Self-improvement loop	None	Limited	failure observation → rule promotion (approval-gated)

flowchart TD
    User["User request"] --> Analyze["Intent analysis<br/>Analyze-First routing"]
    Analyze --> Plan["plan — SPEC authoring"]
    Plan --> Audit["Independent audit<br/>plan-auditor"]
    Audit --> Run["run — TDD/DDD implementation"]
    Run --> Verify["trust-but-verify<br/>verification batch"]
    Verify --> Sync["sync — docs + PR"]
    Sync --> Learn["Decision memory + lessons"]
    Learn -.next session.-> Analyze

The three keys hold each other up

Push the cost key alone and quality silently erodes — rework and debug loops follow, and rework is the most expensive token spend of all. Build quality gates with no learning loop and the same mistakes recur every session. Run an autonomous loop with no cost ceiling and a single runaway task drains the quota. The three keys hold each other up — cost stays economical because quality prevents rework, quality stays enforceable because the loop captures what worked, and the loop stays affordable because cost gates stop it before overage.

Every design decision serves one of these three keys. Which model to use, how deeply to reason, how to spend context — none of it is left to chance turn by turn. The system decides, and records the decision so the next run is smarter.

Cost is determined by assignment, not unit price

Token prices fell 98% over three years (Linux Foundation), yet enterprise AI spend rose 320% in the same window. Volume growth overwhelmed the price drop. Agents spin through dozens to hundreds of steps to solve a single task, burning tokens proportionally. In usage-based pricing this becomes the invoice; in subscription, it eats the weekly quota shared by every model.

Uber deployed Claude Code to 5,000 engineers and burned through a year of coding budget in four months, then imposed monthly token limits. Meta, Amazon, and Microsoft each walked back unlimited-AI policies. Tokenomics — matching the model to the task to raise token efficiency — became the tech industry's new baseline.

Traditional cost control was built for rising unit prices, so it is helpless against this paradox: prices falling while total spend climbs. The bottleneck is not unit price but volume — more precisely, the step count an agent spins before finishing.

The DeepSWE leaderboard (113 tasks, per-effort view) demonstrates this. Within the same Claude family, per-task cost tracks how efficiently a model finishes — not what a token costs.

Model [effort]	Score	Per-task cost	Note
opus-5 [low]	58%±2	$1.66
opus-5 [medium]	69%±1	$3.29	value-for-money knee
opus-5 [high]	73%±2	$6.08	+4pt score, 1.8× cost
opus-5 [xhigh]	73%±3	$9.07	net loss — ties high, +49% cost only
opus-5 [max]	74%±4	$11.84
glm-5.2 [max]	44%±2	$3.92	API-metered disadvantage · valuable under z.ai flat-fee
sonnet-5 [max]	54%±4	$26.40	Pareto-dominated by opus-5 [low]

Opus 5 at its lowest effort scores higher than Sonnet 5 at its highest (58% vs 54%) while costing one-sixteenth as much per task ($1.66 vs $26.40) — even though Sonnet's per-token price is lower. The cause is 268 steps against 36: retry loops, not token rates, write the invoice. Cost is determined by assigning the right model and reasoning depth to each task, not by unit price.

Source: DeepSWE v1.1 leaderboard (datacurve.ai, 113 tasks, 2026-07-25)

---

Quick Start

Install

macOS / Linux / WSL

curl -fsSL https://adk.mo.ai.kr/install.sh | bash

Windows (PowerShell 7.x+)

irm https://adk.mo.ai.kr/install.ps1 | iex

Build from source (Go 1.26+)

git clone https://github.com/modu-ai/moai-adk.git
cd moai-adk && make build

Already installed? Run moai update to move to the latest version. From v3.1.1, before moai update wipes a template-managed directory and redeploys it, it first moves any unmanaged file sitting inside to .moai-backups/<timestamp>/pre-clean/. If that backup fails it stops right there instead of going on to delete — a file you put there yourself is not quietly swept away by a redeploy.

💡 To cut costs — z.ai GLM recommended: signing up via this link grants bonus tokens. The link is also a way to sponsor moai-adk open-source development. Free models (GLM-4.7-Flash, GLM-4.5-Flash) exist too — see the z.ai pricing.

Project initialization

moai init my-project
cd my-project

The interactive wizard auto-detects language, framework, and methodology, walks you through model policy, and generates the Claude Code integration files.

First workflow

claude        # or moai cc — run Claude Code inside the project

/moai plan "Add JWT login"      # author a SPEC
/moai run SPEC-AUTH-001         # TDD/DDD implementation
/moai sync SPEC-AUTH-001        # sync docs + create PR

Natural language works too. /moai "fix the login bug" triggers intent analysis (Analyze-First routing) to read the request and route to the appropriate workflow.

Requirements

Platform	Supported environments	Notes
macOS	Terminal, iTerm2	Full support
Linux	Bash, Zsh	Full support
Windows	WSL (recommended), PowerShell 7.x+	Native cmd.exe unsupported

• Git — required on all platforms
• Claude Code — moai-adk is a harness for Claude Code
• Recommended: gh CLI (PR automation), tmux (CG mode), your language's lint/test toolchain (e.g. golangci-lint)

---

Core Capabilities

One entry point: /moai

Natural language and 16 subcommands feed the same pipeline. /moai plan, /moai run, /moai sync are the backbone of the SPEC pipeline; goal, loop, fix, review, gate, clean, codemaps, e2e, mx, feedback, project, harness, and todo fill out the surroundings.

Four retired subcommands — design · brain · coverage · security. What security did is now covered by