moai-adk

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.

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.

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

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

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)

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)

Full 36 commands: CLI Reference

12-Agent Catalog

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

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

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)

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.

Three execution modes

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:

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.

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}