MoAI-ADK

An Agentic Development Harness for Claude Code — wrapped along three axes: cost, self-improvement, and quality control

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

Official Book: Practical Agentic Coding with Claude Code
A hands-on harness engineering guide by the MoAI-ADK author — book.mo.ai.kr

Official Documentation · Book: Practical Agentic Coding with Claude Code

---

"The model is a stochastic worker moving token by token. It cannot remember, turn to turn, what it should cost, whether the work is good, or where the last session broke off. A harness enforces all three from the outside."

---

MoAI-ADK: A Three-Axis Agentic Harness

MoAI-ADK (Agentic Development Kit) enables Claude Code to produce code — and then makes that code reliable at predictable cost, on a path that keeps improving. A harness wraps the model from the outside. The model is a stochastic worker moving token by token: it remembers neither budget, nor quality bar, nor where the last session broke off. Cost ceilings, passing test suites, a learning loop that compounds, and continuity that survives /clear — none of these can be re-seeded by a prompt every turn. The system must enforce them from the outside.

Three properties, three axes. MoAI-ADK wraps Claude Code along all three, not just one:

• 🪙 Cost — Tokenomics: the same quality for fewer tokens, higher quality for the same tokens.
• 🧠 Self-improvement — Agentic loop engineering: the harness gets better as it runs, turning observation into rules.
• 🛡️ Quality control — Agentic harness: SPEC lifecycle, TRUST 5 gates, and isolation that prevents rework (the single biggest token waste).

It does not replace Claude Code. It wraps, in structure, the parts Claude Code leaves to you — model routing, quality gates, cost control, learning loops, session continuity. A single binary written in Go, it runs on macOS, Linux, and Windows with no extra dependencies.

---

New in v3.1 — Kanban Mode

A session holds one context window, and a long SPEC fills it. Everything that comes after pays for 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 five terminals instead of one. A lead session drives the chain; four companion sessions each own a single column — plan, run, review, sync — and carry only that column's context. Nothing is uncapped: each session still has its own limit. What changes is that no session carries four phases' worth of history, so the same budget goes considerably further, and a finished phase is cleared without losing the card.

Each lane is also free to 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, because the reasoning a lane 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-<run-id>     # companion, in its own terminal
moai cc -k --name run-<run-id>
moai cc -k --name review-<run-id>
moai cc -k --name sync-<run-id>

Companion sessions are launched by hand, one per terminal — a session never spawns a peer. Swap moai cc for moai glm on any lane to put it on the GLM backend.

The board has six columns, backlog → plan → run → review → 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 between phases the lead asks you to /clear the named session, since /clear is user-typed and cannot be sent as an instruction.

Watching the board

moai web serves a local console with a live Kanban screen — the five-session chain alongside the SPEC pipeline, plus Overview, Specs, Monitor, and Settings.

Full guide: Kanban Mode · /moai todo

---

Why Three Axes

Optimizing only cost is a trap. Push the cost axis 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 axes 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 in MoAI-ADK serves one of these three axes. 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.

---

🪙 The Cost Axis — Tokenomics

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.

Cost is determined by assignment, not unit price. 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]	Pass@1	Per-task cost	Output tokens	Steps
claude-opus-5 [low]	58%	$1.66	20k	36
claude-opus-5 [medium]	69%	$3.29	37k	52
claude-opus-5 [high]	73%	$6.08	64k	73
claude-opus-5 [max]	74%	$11.84	118k	99
claude-sonnet-5 [max]	54%	$26.40	214k	268

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.

Four stages: measurement → routing → diet → defense

Routing — the right model and reasoning depth per task

Routing — assign the right model and reasoning depth to each task. Declaratively assign models and reasoning effort (low / medium / high / max) by work phase (plan / run / sync) and SPEC size (Tier S / M / L). Deploy high-reasoning models to planning phases that need deep inference, and light models to implementation phases with mechanical repetition.

• No-Haiku 3-Tier Policy — excludes Haiku from the routing set; Sonnet at low effort takes single-shot, input-dominated work, Opus carries every multi-turn agentic row.
• Profile Matrix — 12 agents × 3 profiles = 36 cells. moai model profile resolves each agent's {model, effort} pair.
• CG Mode — moai cg combines a Claude leader (strategy, planning, audits) with GLM workers (bulk implementation). 60-70% cost savings on implementation-heavy workloads.

DeepSWE Benchmark — where the value-for-money knee sits

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]

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

Verification Economy · Budget Defense — diet context, stop before overage

Verification Economy — diet context, persist evidence to disk. Redirect verbose verification output to disk files, leaving only exit code and bounded tail (max 50 lines) in context. Prompt-cache reuse (cached reads cost 0.1×) and a context-diet /clear strategy (auto-recommendations at 1M 50% / 200K 90% thresholds) keep the window light.

Budget Defense — stop before overage, resume in the next session. A Token Circuit Breaker aborts at the hard limit (default 90%), saves progress to progress.md, and issues a paste-ready resume message. The statusline keeps context usage, cache hit rate, and rate-limit depletion visible at all times.

---

🧠 The Self-Improvement Axis — Agentic Loop Engineering

The cheapest session is the one that does not repeat last session's mistakes. The self-improvement axis turns each run into material for the next: routing decisions and gate evidence are recorded, recurring patterns become rules, and a declared goal keeps the session working until the condition holds.

/moai goal · /moai loop. Declare a completion condition and the session works until it is satisfied or the turn limit (default 30) is reached. --max-turns 0 arms an infinite (auto-compact-driven) goal, bounded by --max-duration and the stagnation guard. /moai loop scans LSP diagnostics · AST-grep · linter in parallel, buckets issues by level, and runs until the queue drains.

Decision memory. Routing decisions, gate evidence, and recurring corrections are recorded so the next session starts from what the last one learned — not from zero.

Harness self-evolution. Observed failure patterns become proposed rule changes, surfaced for approval rather than applied silently.

---

🛡️ The Quality-Control Axis — Agentic Harness

Rework is the worst token waste — a bug that ships and comes back costs more than every routing optimization combined. The quality-control axis makes "done" mean verified done, and isolates work so parallel agents never trample each other.

SPEC 3-Phase Lifecycle

plan → run → sync. Tier S/M/L size classification determines verification depth and PR routing. GEARS format requirements + acceptance criteria judge completion by evidence.

TRUST 5 Quality Gates. Tested (85%+ coverage) · Readable · Unified · Secured · Trackable, applied to every change. Gates judge verification, not agents.

12-Agent Catalog. MoAI custom 11 + built-in Explore. Separate planning and auditing from the start so the authoring side cannot grade its own work.

Extension Points — duplicate proven patterns for project-specific reuse

Harness v4 Builder. Natural language request → domain·goal·constraint extraction → approval gate → project-specific agents·skills·commands·hooks scaffolding.

@MX Tags. Inline code annotations where AI agents exchange context, invariants, and danger zones.

worktree isolation. Give each SPEC its own working tree. Enter one with moai cc -w <name>, or add --spawn to open it in a new window while keeping the current session.

---

Infrastructure Sustains All Three Axes

A single Go binary with no extra dependencies, running on macOS, Linux, and Windows, is the substrate beneath all three axes — not beneath tokenomics alone. The hook system enforces gates mechanically, the statusline surfaces cost and context in real time, and the SPEC lifecycle keeps work resumable across /clear. Every axis rides on the same binary; none is an afterthought.

---

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

Project Initialization

moai init my-project

Interactive wizard auto-detects language, framework, and methodology, selects model policy, and generates Claude Code integration files.

First Workflow

claude        # launch 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

Prerequisites

• Git required on all platforms
• Claude Code — MoAI-ADK is a harness for Claude Code
• Recommended: gh CLI (PR automation) · tmux (CG mode) · language linter/test toolchain (e.g., golangci-lint)

---

Reference

/moai Slash Commands (16)

Subcommand	Role
plan / run / sync	SPEC 3-phase pipeline
project / harness	Project docs+harness generation · harness lifecycle
goal / loop / fix	Declarative goal loops · iterative fixes · single-pass fixes
review / gate / clean	Code review (--deep for multi-agent adversarial vulnerability scan) · pre-commit quality gates · dead code removal
mx / codemaps / feedback	@MX annotations · architecture docs · GitHub issue reporting
e2e / todo	Multi-platform E2E tests (web/mobile/desktop, CLI-first) · Kanban backlog queue
(natural language)	Analyze-First routing: autonomous plan → run → sync pipeline

4 Retired Subcommands: design · brain · coverage · security (SPEC-SUBCOMMAND-RETIRE-001, status: completed). security was replaced by the moai-ref-owasp-checklist + moai-ref-llm-security skills; e2e was revived by E2E-REVIVAL and is currently active.

→ Details: Workflow Commands · Utility Commands

CLI Commands (13 frequently used)

Command	Description
moai init	Interactive project setup (auto-detects language/framework/methodology)
moai doctor	System state diagnosis and environment verification
moai status	Project status summary (Git branch, quality metrics)
moai update	Update to latest version (auto-rollback supported)
moai cc / moai glm / moai cg	Claude-only / GLM-only / hybrid Claude leader + GLM worker sessions
moai worktree <sync|done|remove|clean|recover|snapshot|verify|restore>	Git worktree maintenance (entering a worktree is the launchers' job)
moai session <list|register|current>	Multi-session coordination
moai spec <audit|archive|lint|list|new>	SPEC lifecycle tools
moai goal <arm|status|clear>	Goal engine CLI
moai harness <status|apply|rollback|disable>	Harness learning lifecycle
moai handoff <save|list>	Session handoff records
moai preference <list|decay-scan|toggle>	Decision memory management
moai web	Web Console — 5 screens (Overview · Kanban · Specs · Monitor · Settings), 10-tab settings

Full command list: CLI Reference

MCP Server

moai init provisions exactly one active MCP entry by default — the self-hosted moai mcp-server (a local stdio server). It exposes 17 MoAI-specific tools across five groups. Four documented-but-disabled entries (context7, chrome-devtools, playwright, ast-grep) are activated via moai mcp add <name>. The generic moai mcp add|remove|list CLI manages entries via an atomic-RMW seam — users never hand-edit .mcp.json.

Group	Tools	Purpose
SPEC lifecycle	spec_progress, spec_audit, spec_drift	Era classification + drift detection
Verification	verify_snapshot, verify_trend	Per-key evidence snapshots
Goal + session	goal_arm, goal_status, session_list	Autonomous loop + multi-session coordination
Cross-model audit	audit_multi, codex_audit, glm_audit, audit_cache	Multi-auditor convergence
Codex delegation	codex_task, codex_setup, codex_job_*	Background cross-model jobs

All backends are fail-open: GLM (~/.moai/.env.glm) and codex (~/.codex/auth.json) are optional — an unavailable backend returns inconclusive, never a hard error.

Details: MCP Server Guide · Claude Code MCP

12-Agent Catalog

Category	Agent	Cost	Role
Manager	manager-spec	🔴	Plan-phase SPEC authoring
	manager-develop	🔴	Run-phase TDD/DDD/autofix implementation
	manager-docs	🔵	Sync-phase documentation
	manager-git	🩵	PR creation and routing
	manager-design	🟠	Design-phase collaboration (Claude Design)
	manager-kanban	🔴	Hierarchical-team Tier L coordination (sole Agent-carrier, depth-2 sealed)
Evaluator	plan-auditor	🔴	Independent plan audit (bias prevention)
	sync-auditor	🔴	4-dimensional quality scoring (Functionality 40 · Security 25 · Craft 20 · Consistency 15)
Builder	builder-harness	🟠	Project-specific agents, skills, commands, hooks scaffolding
Advisor	super-advisor	🔵	On-demand high-reasoning consultation (E1-E4 escalation)
Specialist	e2e-tester	🟠	Web/mobile/desktop E2E test execution (CLI-first)
Built-in	Explore	⚪	Read-only codebase exploration

Cost colors follow the default medium profile's model×effort cells (inspect via moai model profile): 🔴 opus+high · 🟠 opus+medium · 🔵 opus+low · 🩵 sonnet+low · ⚪ session-model inherit (user-added agents). Assignments shift when switching profiles (high/low). Progress of long-running delegations is recorded on the Task channel and relayed by the orchestrator as an icon Progress Board.

TRUST 5 Quality Gates

Criterion	Meaning	Verification
Tested	Tested	85%+ coverage, characterization tests, unit tests pass
Readable	Readable	Clear naming, consistent style, lint errors 0
Unified	Unified	Consistent formatting, import order, project structure compliance
Secured	Secured	OWASP compliance, input validation, security warnings 0
Trackable	Trackable	Conventional commits, issue references, structured logging

Methodology Selection (TDD vs DDD)

flowchart TD
    A["Project analysis"] --> B{"New project or<br/>10%+ test coverage?"}
    B -->|"Yes"| C["TDD (default)"]
    B -->|"No"| D["DDD"]
    C --> F["RED → GREEN → REFACTOR"]
    D --> G["ANALYZE → PRESERVE → IMPROVE"]

Methodology	Cycle	Target
TDD (default)	RED → GREEN → REFACTOR	New projects and feature work
DDD	ANALYZE → PRESERVE → IMPROVE	Existing code with <10% coverage

Kanban Mode

--kanban (short -k) is a session-launcher switch that arms a kanban_chain goal preset — driving a single SPEC through plan → run → verify → sync with multi-session board coordination. The board's backbone is the Origin-Trail Chain: an append-only JSONL lineage tree that tracks worktree ancestry, solves depth amnesia (root-to-leaf chain recovery after /clear), and detects dead leader sessions via heartbeat staleness.

Concept	What it does
Origin-Trail Chain	Append-only JSONL event stream at .moai/state/chain/events.jsonl
WorktreeNode (13 fields)	Per-session state: ID, parent, depth, origin chain, milestone, resume target
CWD-collision resolution	(worktree_path, session_id) pair disambiguates reused paths
Depth ceiling	Caps nesting complexity

Available now: moai cc -k (or moai glm -k) starts the lead and -k --name <role>-<run-id> joins each companion — launched by hand, one per terminal. moai chain <status|lineage|back|list|prune> reads the lineage, and moai todo <add|list|next|done> operates the backlog column. The launch sequence is in the "New in v3.1 — Kanban Mode" section above.

Details: Kanban Mode Guide

---

Reading the Statusline

🤖 Opus │ 🧠 xhigh·t │ ♻️ 87% │ 🔅 v2.1.212 │ 🗿 v3.0.1 │ ⏳ 2h 34m │ 💬 MoAI
🪫 CW: ████████░░ 88% (⚠️/clear) │ 🔋 5H: ████░░░░░░ 45% (4h 30m) │ 🪫 7D: ████████░░ 82% (Jan 21)
📁 moai-adk-go │ 🔀 modu-ai/moai-adk | 🅱️ feat/statusline ↑2 +3 │ 💾 +1 M2 ?0 │ 📋 [run SPEC-AUTH-001-run] │ 💌 PR #1042 (⌥approved)

Element	Meaning
🤖 Model	Current active model
🧠 effort	Reasoning effort level — ·t suffix when extended reasoning active
♻️ Cache hit rate	Prompt cache hit rate
CW: Context	Context window usage rate + 2-stage /clear markers (⚠️ soft, 🛑 hard)
5H / 7D	Pricing plan usage rate + reset time
📁 Directory	Project directory name
🔀 Repo	GitHub repo identity owner/name
🅱️ Branch	Current branch + ↑ahead ↓behind + +dirty count
💾 git status	staged / modified / untracked counts
📋 Task	Active SPEC workflow [command SPEC-ID-phase]
💌 PR	Active GitHub PR number + review state (⌥state)

Details: Statusline Guide

---

Claude × GLM Multi-LLM

MoAI-ADK supports z.ai GLM as an alternative backend for Claude Code. Switching is environment-variable only — no code changes, and the harness, SPEC workflow, and quality gates behave identically on every backend.

Item	Details
GLM Coding Plan	From $10/month (sign-up)
Compatibility	Drop-in with Claude Code — no code changes
Models	glm-5.3, glm-4.7, glm-4.5-air, plus free models

Three execution modes

Command	Leader	Workers	tmux	Cost saving	Use for
moai cc	Claude	Claude	not required	—	Highest quality, complex work
moai glm	GLM	GLM	recommended	~70%	Cost optimization
moai cg	Claude	GLM	required	~60%	Quality + cost balance

CG mode is the hybrid: a Claude leader owns strategy, planning, and audits while GLM workers carry bulk implementation, wired through tmux session-level environment isolation.

moai glm sk-your-glm-api-key   # save the key once
moai cg                        # enter CG mode (Claude leader + GLM workers)

Default model mapping

Each Claude tier maps to a GLM model through the ANTHROPIC_DEFAULT_*_MODEL environment variables:

Claude tier	GLM model	Context
Opus	glm-5.3	1M
Sonnet	glm-5.3	1M
Haiku	glm-5.3	1M
Fable	glm-5.3	1M

Free models are also available (GLM-4.7-Flash, GLM-4.5-Flash). See z.ai pricing for the full table.

→ Details: Multi-LLM guide

---

FAQ

Q: Why doesn't every function have an @MX tag?

Normal. Tags mark high-fan-in, complex, or dangerous code. Most code in any project won't hit any tag threshold, and a file without tags is not a defect.

Q: What does the statusline version display mean?

🗿 v3.0.1 ⬆️ v3.0.2

The first value is the currently installed MoAI-ADK version; the arrow indicates an available update. Disappears after running moai update.

Q: Can I use Claude only without GLM?

Yes. moai cc launches a Claude-only session. CG mode (moai cg, Claude leader + GLM workers) and GLM-only (moai glm) are cost-saving options; the harness·SPEC workflow·quality gates work identically across all three modes.

Q: Does it work on existing projects?

Yes. moai init detects project state and selects methodology — DDD (characterization tests fix behavior, then incremental improvement) for existing code with <10% coverage, TDD for new/well-tested code.

---

Community and Documentation

Contributing

Contributions are welcome. See CONTRIBUTING.md for detailed procedures.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Write tests (TDD for new code, characterization tests for existing code)
4. Verify tests, lint, format pass: make test · make lint · make fmt
5. Commit with Conventional commit message and open pull request

Code quality requirements: 85%+ coverage · lint errors 0 · type errors 0 · Conventional commits

Community

• Issues — Bug reports, feature requests (use /moai feedback in Claude Code)

License

Apache License 2.0 — see LICENSE file for details.

Documentation Guide

adk.mo.ai.kr online documentation is organized into 12 sections.

Section	Description
Getting Started	Introduction, installation, Windows guide, init wizard, quickstart, CLI overview, FAQ
Core Concepts	MoAI-ADK identity, constitution, harness engineering, SPEC-based development, DDD, TRUST 5
Workflow Commands	plan · run · sync — SPEC pipeline backbone
Utility Commands	fix · loop · gate · review · clean · codemaps · e2e · feedback · goal
CLI Reference	All moai binary commands — status, profile, doctor, update, web, goal, handoff, harness, init, worktree, etc.
Claude Code Guide	Claude Code integration — basics, context·memory, agentic, extensibility (skills·hooks·plugins)
Multi-LLM	CG mode and model policy
Cost Optimization	Prompt caching strategies and token cost reduction
Guides	CI automation, multi-LLM CI, and other operational recipes
Git Worktree	Worktree guide for parallel SPEC development, examples, FAQ
Advanced	Tokenomics overview, token budget, statusline, settings.json, hooks, @MX tags, skill guide, Harness v4 Builder, self-evolution, decision memory, catalog system, security notes, CLAUDE.md/agent guide
Contributing	Open-source contribution guide

Links

• Official Documentation
• Book: Practical Agentic Coding with Claude Code
• CHANGELOG
• Claude Code

---

Star History

_{Built by the MoAI-ADK team · adk.mo.ai.kr}