moai-adk

---

"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.

---

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://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bash

Windows (PowerShell 7.x+)

irm https://raw.githubusercontent.com/modu-ai/moai-adk/main/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 (15)

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	Multi-platform E2E tests (web/mobile/desktop, CLI-first)
(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 — 6-tab settings console

Full 36 commands: CLI Reference

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-lead	🔴	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

---

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.2, 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.2	1M
Sonnet	glm-4.7	202K
Haiku	glm-4.5-air	128K
Fable	glm-5.2	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