MoAI-ADK: A Verification-Driven Harness for Claude Code, and Factory Mode's Leader-Plus-Lanes Context Split

What it is

MoAI-ADK is an open-source agent orchestration harness from the modu-ai team. It is written in Go (Go 1.26 or newer is required) and licensed under Apache-2.0. The release badge on the repository shows v3.1.3, and the What's New section announces v3.2 with a feature called Factory Mode.

The project does not try to train a better coding model. It wraps an existing coding agent, mainly Claude Code, in an outside structure so that the code it produces can be trusted. The repository also ships documentation in English, Korean, Japanese and Chinese, links a companion book titled Practical Agentic Coding with Claude Code, and runs CI, CodeQL and Codecov checks.

The core claim: move three duties outside the model

The README opens with one sentence that explains the whole design. The model is a stochastic worker moving token by token. Between turns it cannot remember what it used and how much, it cannot tell whether the result is good, and it does not know how far the last session got. A harness enforces all three from the outside.

In engineering terms those are budget, quality and progress. MoAI-ADK treats them as duties of deterministic code, not of the model. This differs from the common habit of writing ever longer prompts. The harness does not ask the model to behave. It limits and checks the model.

Factory Mode: the architecture

Factory Mode targets the context window. A session spends one window. A long SPEC fills it, and every later task carries everything that came before. The plan finished long ago, yet it stays in the window through the whole review, and the review stays through the whole write-up. The usual escape is /clear, but that throws away useful context together with the baggage.

Factory Mode splits the work across one leader session and several numbered lane sessions. The leader watches the queue and hands cards to free lanes. A card does not change sessions at each stage. It goes whole into one lane, and that lane carries it through plan, run and sync in order, inside its own session. Each stage is spawned as an Agent() subagent, and the lane itself only orchestrates. Nothing is uncapped: the limit of each session is still there. What changes is where history accumulates. One card's history builds up only in the lane that owns it, so the same budget goes further, and a lane empties its context after each card before it takes the next.

How it runs

Entry uses two tokens. moai cc -f (long form --factory) opens the leader. moai cc -l (long form --lane) joins the running factory as a lane. Neither takes a value, and the lane number is assigned automatically. Combining -f with -l is an error. A value after either token, such as moai cc -l lane-2, is refused with a one-line message that names the correct form. The old -k entry of the multi-session board mode is removed, and moai cg exits with a migration notice that you can preview with moai migrate cg. There is no moai gpt command: GPT models run through moai codex, which has no leader entry and can only join as a lane. The backend is chosen per lane. moai cc -l is a Claude lane, moai glm -l is a GLM lane, and moai codex -l is a Codex lane. The documentation suggests GLM for the leader seat (moai glm -f), because that seat watches a queue and carries cards instead of passing verdicts, and a cheap model is fine at waiting. If one account starts to hit 429 errors, spreading lanes across accounts helps. The text says this mix is only one example, and a single backend for every session is fine too. To handle many cards at once, run -l again. A lane number is skipped only while a live session holds it. A dead lane's claim no longer blocks its number, but automatic assignment always takes the highest live number plus one, so it never fills a gap in the middle. Lane ownership is stored in ~/.moai/db/<project-key>/factory/factory.db. When the base directory is a temporary directory and no absolute MOAI_HOME override is set, the record goes under the project-local <base>/.moai/db/<project-key>/factory/ instead, the same exception that the backlog queue makes. The old .moai/state/factory/workers.json is imported once and kept only as rollback evidence.

A lane runs at most 10 Agent() subagents at once, and spawns that can write are isolated in their own worktrees. The guidance is to bring up the first lane, confirm it produces output, and only then start the rest. A card is never split across lanes. A factory run also records the process identity of the session that owns it. A run whose leader has died is retired automatically when the next lane joins, so the join does not stall on AMBIGUOUS_FACTORY. The reverse case is covered as well: if a lane joins while the run record is missing or retired but a live leader session exists, the join verifies that leader using the pid and a process start fingerprint.

Performance and cost: where is the evidence?

The README excerpt gives no benchmark numbers. There is no throughput figure, no token cost comparison, and no before-and-after defect rate.

What it offers is a structural argument: because a card's history lives only in its own lane, the same budget goes further. That is a reasonable mechanism, but without published measurements it should be read as a hypothesis, not as a proven gain. A team that wants to judge it can track a few measurable things: average context use per card, how well a lane reuses its window after it empties, the rate of 429 errors, and the coordination cost between leader and lanes.

Impact on developers and teams

For a solo developer, Factory Mode gives a parallel setup without a custom scheduler: open several terminals and run moai cc -l in each. For a team, state sits in SQLite files under a project key, which helps audit and recovery.

Multi-backend support lets a team mix providers by cost and quota instead of betting on one. More broadly, the project reflects a shift in this field. The contest is moving from the model itself to the process and verification layer around the model.

Limits and outlook

First, lanes must be started by hand, one terminal each, because a session cannot launch another session. That caps full automation. Second, the public material has no quantitative benchmark. Third, the process-identity checks and the one-time import of legacy state show that crash recovery already carries real complexity, and users should understand those edge cases.

Fourth, the rule that a card is never split means one very large task can still fill the window of a single lane. Useful next steps would be a published measurement report, more backends, and finer card-splitting policies. In short, MoAI-ADK is worth watching. Before it enters a production flow, measure it yourself on a small set of real tasks.