MoAI-ADK

Agentic Development Kit for Claude Code

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

Official Documentation

📚 Official Documentation

"The purpose of vibe coding is not rapid productivity but code quality."

MoAI-ADK is a high-performance AI development environment for Claude Code. 27 specialized AI agents and 52 skills collaborate to produce quality code. It automatically applies TDD (default) for new projects and feature development, or DDD for existing projects with minimal test coverage, and supports dual execution modes with Sub-Agent and Agent Teams.

A single binary written in Go -- runs instantly on any platform with zero dependencies.

Why MoAI-ADK?

We completely rewrote the Python-based MoAI-ADK (~73,000 lines) in Go.

Key Numbers

• 34,220 lines of Go code, 32 packages
• 85-100% test coverage
• 27 specialized AI agents + 52 skills
• 18 programming languages supported
• 16 Claude Code hook events

Harness Engineering Architecture

MoAI-ADK implements the Harness Engineering paradigm — designing the environment for AI agents rather than writing code directly.

"Human steers, agents execute." — The engineer's role shifts from writing code to designing the harness: SPECs, quality gates, and feedback loops.

System Requirements

Prerequisites:

• Git must be installed on all platforms
• Windows users: Git for Windows is required (includes Git Bash)
  • Use WSL (Windows Subsystem for Linux) for the best experience
  • PowerShell 7.x or later is supported as an alternative
  • Legacy Windows PowerShell 5.x and cmd.exe are not supported

Quick Start

1. Installation

macOS / Linux / WSL

curl -fsSL https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bash

Windows (PowerShell 7.x+)

Recommended: Use WSL with the Linux installation command above for the best experience.

irm https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.ps1 | iex

Requires Git for Windows to be installed first.

Build from Source (Go 1.26+)

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

Prebuilt binaries are available on the Releases page.

2. Windows-Specific Issues

Korean Username Path Errors

If your Windows username contains non-ASCII characters (Korean, Chinese, etc.),
you may encounter EINVAL errors due to Windows 8.3 short filename conversion.

Workaround 1: Set an alternative temp directory:

# Command Prompt
set MOAI_TEMP_DIR=C:\temp
mkdir C:\temp 2>nul

# PowerShell
$env:MOAI_TEMP_DIR="C:\temp"
New-Item -ItemType Directory -Path "C:\temp" -Force

Workaround 2: Disable 8.3 filename generation (requires admin):

fsutil 8dot3name set 1

Workaround 3: Create a new Windows user account with ASCII-only username.

3. Initialize a Project

moai init my-project

An interactive wizard auto-detects your language, framework, and methodology, then generates Claude Code integration files.

4. Start Developing with Claude Code

# After launching Claude Code
/moai project                            # Generate project docs (product.md, structure.md, tech.md)
/moai plan "Add user authentication"     # Create a SPEC document
/moai run SPEC-AUTH-001                   # DDD/TDD implementation
/moai sync SPEC-AUTH-001                  # Sync docs & create PR

graph LR
    A["🔍 /moai project"] --> B["📋 /moai plan"]
    B -->|"SPEC Document"| C["🔨 /moai run"]
    C -->|"Implementation Complete"| D["📄 /moai sync"]
    D -->|"PR Created"| E["✅ Done"]

MoAI Development Methodology

MoAI-ADK automatically selects the optimal development methodology based on your project's state.

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

    style C fill:#4CAF50,color:#fff
    style E fill:#2196F3,color:#fff

TDD Methodology (Default)

The default methodology for new projects and feature development. Write tests first, then implement.

For brownfield projects (existing codebases), TDD is enhanced with a pre-RED analysis step: read existing code to understand current behavior before writing tests.

DDD Methodology (Existing Projects with < 10% Coverage)

A methodology for safely refactoring existing projects with minimal test coverage.

ANALYZE   → Analyze existing code and dependencies, identify domain boundaries
PRESERVE  → Write characterization tests, capture current behavior snapshots
IMPROVE   → Improve incrementally under test protection. /simplify runs automatically after IMPROVE completes.

The methodology is automatically selected during moai init (--mode <ddd|tdd>, default: tdd) and can be changed via development_mode in .moai/config/sections/quality.yaml.

Note: MoAI-ADK v2.5.0+ uses binary methodology selection (TDD or DDD only). The hybrid mode has been removed for clarity and consistency.

Auto Quality & Scale-Out Layer

MoAI-ADK v2.6.0+ integrates two Claude Code native skills that MoAI invokes autonomously — no flags or manual commands required.

/simplify — Automatic Quality Pass

Uses parallel agents to review changed code for reuse opportunities, quality issues, efficiency, and CLAUDE.md compliance, then auto-fixes findings. MoAI calls this directly after every implementation cycle — no configuration needed.

/batch — Parallel Scale-Out

Spawns dozens of agents in isolated git worktrees for large-scale parallel work. Each agent runs tests and reports results; MoAI merges them. Auto-triggered per workflow:

AI Agent Orchestration

MoAI is a strategic orchestrator. Rather than writing code directly, it delegates tasks to 27 specialized agents.

graph LR
    U["👤 User Request"] --> M["🗿 MoAI Orchestrator"]

    M --> MG["📋 Manager (8)"]
    M --> EX["⚡ Expert (9)"]
    M --> BL["🔧 Builder (3)"]
    M --> TM["👥 Team (8)"]

    MG --> MG1["spec · ddd · tdd · docs<br/>quality · project · strategy · git"]
    EX --> EX1["backend · frontend · security · devops<br/>performance · debug · testing · refactoring · chrome-ext"]
    BL --> BL1["agent · skill · plugin"]
    TM --> TM1["researcher · analyst · architect · designer<br/>backend-dev · frontend-dev · tester · quality"]

    style M fill:#FF6B35,color:#fff
    style MG fill:#4CAF50,color:#fff
    style EX fill:#2196F3,color:#fff
    style BL fill:#9C27B0,color:#fff
    style TM fill:#FF9800,color:#fff

Agent Categories

52 Skills (Progressive Disclosure)

Managed through a 3-level progressive disclosure system for token efficiency:

Model Policy (Token Optimization)

MoAI-ADK assigns optimal AI models to each of 27 agents based on your Claude Code subscription plan. This maximizes quality within your plan's rate limits.

Why does this matter? The Plus $20 plan does not include Opus access. Setting Low ensures all agents use only Sonnet and Haiku, preventing rate limit errors. Higher plans benefit from Opus on critical agents (security, strategy, architecture) while using Sonnet/Haiku for routine tasks.

Agent Model Assignment by Tier

Manager Agents

Expert Agents

Builder Agents

Team Agents

Configuration

# During project initialization
moai init my-project          # Interactive wizard includes model policy selection

# Reconfigure existing project
moai update                   # Interactive prompts for each configuration step

During moai update, you'll be asked:

• Reset model policy? (y/n) - Re-run model policy configuration wizard
• Update GLM settings? (y/n) - Configure GLM environment variables in settings.local.json

Default policy is High. GLM settings are isolated in settings.local.json (not committed to Git).

Dual Execution Modes

MoAI-ADK provides both Sub-Agent and Agent Teams execution modes supported by Claude Code.

graph TD
    A["🗿 MoAI Orchestrator"] --> B{"Select Execution Mode"}
    B -->|"--solo"| C["Sub-Agent Mode"]
    B -->|"--team"| D["Agent Teams Mode"]
    B -->|"Default (Auto)"| E["Auto Selection"]

    C --> F["Sequential Expert Delegation<br/>Task() → Expert Agent"]
    D --> G["Parallel Team Collaboration<br/>TeamCreate → SendMessage"]
    E -->|"High Complexity"| D
    E -->|"Low Complexity"| C

    style C fill:#2196F3,color:#fff
    style D fill:#FF9800,color:#fff
    style E fill:#4CAF50,color:#fff

Agent Teams Mode (Default)

MoAI-ADK automatically analyzes project complexity and selects the optimal execution mode:

Agent Teams Mode uses parallel team-based development:

• Multiple agents work simultaneously, collaborating through a shared task list
• Real-time coordination via TeamCreate, SendMessage, and TaskList
• Best suited for large-scale feature development and multi-domain tasks

/moai plan "large feature"          # Auto: researcher + analyst + architect in parallel
/moai run SPEC-XXX                  # Auto: backend-dev + frontend-dev + tester in parallel
/moai run SPEC-XXX --team           # Force Agent Teams mode

Quality Hooks for Agent Teams:

• TeammateIdle Hook: Validates LSP quality gates before teammate goes idle (errors, type errors, lint errors)
• TaskCompleted Hook: Verifies SPEC document exists when task references SPEC-XXX patterns
• All validation uses graceful degradation - warnings logged but work continues

Sub-Agent Mode (--solo)

A sequential agent delegation approach using Claude Code's Task() API.

• Delegates a task to a single specialized agent and receives the result
• Progresses step by step: Manager → Expert → Quality
• Best suited for simple and predictable workflows

/moai run SPEC-AUTH-001 --solo      # Force Sub-Agent mode

MoAI Workflow

Plan → Run → Sync Pipeline

MoAI's core workflow consists of three phases:

graph TB
    subgraph Plan ["📋 Plan Phase"]
        P1["Explore Codebase"] --> P2["Analyze Requirements"]
        P2 --> P3["Generate SPEC Document (EARS Format)"]
    end

    subgraph Run ["🔨 Run Phase"]
        R1["Analyze SPEC & Create Execution Plan"] --> R2["DDD/TDD Implementation"]
        R2 --> R3["TRUST 5 Quality Validation"]
    end

    subgraph Sync ["📄 Sync Phase"]
        S1["Generate Documentation"] --> S2["Update README/CHANGELOG"]
        S2 --> S3["Create Pull Request"]
    end

    Plan --> Run
    Run --> Sync

    style Plan fill:#E3F2FD,stroke:#1565C0
    style Run fill:#E8F5E9,stroke:#2E7D32
    style Sync fill:#FFF3E0,stroke:#E65100

Execution Mode Selection Gate

When transitioning from Plan to Run phase, MoAI automatically detects the current execution environment (cc/glm/cg) and presents a selection UI for the user to confirm or change the mode before implementation begins.

graph LR
    A["Plan Complete"] --> B["Detect Environment"]
    B --> C{"Mode Selection UI"}
    C -->|"CC"| D["Claude-only Execution"]
    C -->|"GLM"| E["GLM-only Execution"]
    C -->|"CG"| F["Claude Leader + GLM Workers"]

This gate ensures the correct execution mode is used regardless of the environment state, preventing mode mismatches during implementation.

/moai Subcommands

All subcommands are invoked within Claude Code as /moai <subcommand>.

Core Workflow

Quality & Testing

Documentation & Codebase

Default Workflow

Execution Mode Flags

Control how agents are dispatched during workflow execution:

--team supports three execution environments:

New in v2.7.1: CG mode is now the default team mode. When using --team, the system runs in CG mode unless explicitly changed with moai cc or moai glm.

Note: moai cg uses tmux pane-level env isolation to separate Claude leader from GLM workers. If switching from moai glm, moai cg automatically resets GLM settings first — no need to run moai cc in between.

Autonomous Development Loop (Ralph Engine)

An autonomous error-fixing engine that combines LSP diagnostics with AST-grep:

/moai fix       # Single pass: scan → classify → fix → verify
/moai loop      # Iterative fix: repeats until completion marker detected (max 100 iterations)

How the Ralph Engine works:

1. Parallel Scan: Runs LSP diagnostics + AST-grep + linters simultaneously
2. Auto-Classification: Classifies errors from Level 1 (auto-fix) to Level 4 (user intervention)
3. Convergence Detection: Applies alternative strategies when the same error repeats
4. Completion Criteria: 0 errors, 0 type errors, 85%+ coverage

Recommended Workflow Chains

New Feature Development:

/moai plan → /moai run SPEC-XXX → /moai review → /moai coverage → /moai sync SPEC-XXX

Bug Fix:

/moai fix (or /moai loop) → /moai review → /moai sync

Refactoring:

/moai plan → /moai clean → /moai run SPEC-XXX → /moai review → /moai coverage → /moai codemaps

Documentation Update:

/moai codemaps → /moai sync

TRUST 5 Quality Framework

Every code change is validated against five quality criteria:

Task Metrics Logging

MoAI-ADK automatically captures Task tool metrics during development sessions:

• Location: .moai/logs/task-metrics.jsonl
• Captured Metrics: Token usage, tool calls, duration, agent type
• Purpose: Session analytics, performance optimization, cost tracking

Metrics are logged by the PostToolUse hook when Task tool completes. Use this data to analyze agent efficiency and optimize token consumption.

CLI Commands

Architecture

moai-adk/
├── cmd/moai/             # Application entry point
├── internal/             # Core private packages
│   ├── astgrep/          # AST-grep integration for structural code analysis
│   ├── cli/              # Cobra CLI command definitions
│   ├── config/           # Thread-safe YAML configuration management
│   ├── core/
│   │   ├── git/          # Git operations (branches, worktrees, conflict detection)
│   │   ├── project/      # Project initialization, language/framework detection
│   │   └── quality/      # TRUST 5 quality gates, parallel validators
│   ├── defs/             # Language definitions and framework detection
│   ├── git/              # Git convention validation engine
│   ├── hook/             # Compiled hook system (16 events, JSON protocol)
│   ├── loop/             # Ralph feedback loop (state machine, convergence detection)
│   ├── lsp/              # LSP client (16+ languages, parallel server management)
│   ├── manifest/         # File provenance tracking (SHA-256 integrity)
│   ├── merge/            # 3-way merge engine (6 strategies)
│   ├── rank/             # MoAI Rank sync and transcript management
│   ├── resilience/       # Retry policies and circuit breakers
│   ├── shell/            # Shell integration (worktree navigation)
│   ├── statusline/       # Claude Code status line integration
│   ├── template/         # Template deployment (go:embed), settings generation
│   ├── ui/               # Interactive TUI (selectors, checkboxes, wizards)
│   └── update/           # Binary self-update mechanism
├── pkg/                  # Public library packages
│   ├── models/           # Shared data models
│   └── version/          # Build version metadata
└── Makefile              # Build automation

Key Package Coverage

Sponsors

z.ai GLM 5

MoAI-ADK partners with z.ai GLM 5 to provide a cost-effective AI development environment.

Sign up for GLM 5 (extra 10% discount) -- Referral rewards are used to fund MoAI open-source development.

CG Mode (Claude + GLM Hybrid)

CG Mode is a hybrid mode where the Leader uses Claude API while Workers use GLM API. It's implemented via tmux session-level environment variable isolation.

How It Works

moai cg execution
    │
    ├── 1. Inject GLM config into tmux session env
    │      (ANTHROPIC_AUTH_TOKEN, BASE_URL, MODEL_* vars)
    │
    ├── 2. Remove GLM env from settings.local.json
    │      → Leader pane uses Claude API
    │
    └── 3. Set CLAUDE_CODE_TEAMMATE_DISPLAY=tmux
           → Workers inherit GLM env in new panes

┌─────────────────────────────────────────────────────────────┐
│  LEADER (current tmux pane, Claude API)                     │
│  - Orchestrates workflow when /moai --team runs             │
│  - Handles plan, quality, sync phases                       │
│  - No GLM env → uses Claude API                             │
└──────────────────────┬──────────────────────────────────────┘
                       │ Agent Teams (new tmux panes)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  TEAMMATES (new tmux panes, GLM API)                        │
│  - Inherit tmux session env → use GLM API                   │
│  - Execute implementation tasks in run phase                │
│  - Communicate with leader via SendMessage                  │
└─────────────────────────────────────────────────────────────┘

Usage

# 1. Save GLM API key (once)
moai glm sk-your-glm-api-key

# 2. Verify tmux environment (skip if already in tmux)
# If you need a new tmux session:
tmux new -s moai

# TIP: Set VS Code terminal default to tmux for automatic tmux environment.
# This allows you to skip this step entirely.

# 3. Enable CG mode
moai cg

# 4. Start Claude Code in the SAME pane (critical!)
claude

# 5. Run team workflow
/moai --team "your task description"

Important Notes

Mode Comparison

Display Modes

Agent Teams supports two display modes:

CG Mode only supports Leader/Worker API separation in tmux display mode.

@mx Tag System

MoAI-ADK uses @mx code-level annotation system to communicate context, invariants, and danger zones between AI agents.

What are @mx Tags?

@mx tags are inline code annotations that help AI agents understand your codebase faster and more accurately.

// @MX:ANCHOR: [AUTO] Hook registry dispatch - 5+ callers
// @MX:REASON: [AUTO] Central entry point for all hook events, changes have wide impact
func DispatchHook(event string, data []byte) error {
    // ...
}

// @MX:WARN: [AUTO] Goroutine executes without context.Context
// @MX:REASON: [AUTO] Cannot cancel goroutine, potential resource leak
func processAsync() {
    go func() {
        // ...
    }()
}

Tag Types

Why doesn't every code have @mx tags?

The @mx tag system is NOT designed to add tags to all code. The core principle is to "mark only the most dangerous/important code that AI needs to notice first."

Most code doesn't meet any criteria, so it has no tags. This is normal.

Example: Tag Decision

// ❌ No tag (fan_in = 1, low complexity)
func calculateTotal(items []Item) int {
    total := 0
    for _, item := range items {
        total += item.Price
    }
    return total
}

// ✅ @MX:ANCHOR added (fan_in = 5)
// @MX:ANCHOR: [AUTO] Config manager load - 5+ callers
// @MX:REASON: [AUTO] Entry point for all CLI commands
func LoadConfig() (*Config, error) {
    // ...
}

Configuration (.moai/config/sections/mx.yaml)

thresholds:
  fan_in_anchor: 3        # < 3 callers = no ANCHOR
  complexity_warn: 15     # < 15 complexity = no WARN
  branch_warn: 8          # < 8 branches = no WARN

limits:
  anchor_per_file: 3      # Max 3 ANCHOR tags per file
  warn_per_file: 5        # Max 5 WARN tags per file

exclude:
  - "**/*_generated.go"   # Exclude generated files
  - "**/vendor/**"        # Exclude external libraries
  - "**/mock_*.go"        # Exclude mock files

Running MX Tag Scan

# Scan entire codebase (Go projects)
/moai mx --all

# Preview only (no file modifications)
/moai mx --dry

# Scan by priority (P1 only)
/moai mx --priority P1

# Scan specific languages only
/moai mx --all --lang go,python

Why Other Projects Also Have Few MX Tags

Core Principle

The @mx tag system optimizes "Signal-to-Noise Ratio":

• ✅ Mark only truly important code → AI quickly identifies core areas
• ❌ Tag all code → Increases noise, makes important tags harder to find

Frequently Asked Questions

Q: Why doesn't every Go code have @mx tags?

A: This is normal. @mx tags are added "only where needed." Most code is simple and safe enough that tags aren't required.

See the "@mx Tag System" section above for details.

Q: How do I customize which statusline segments are displayed?

The statusline supports 4 display presets plus custom configuration:

• Full (default): All 8 segments displayed
• Compact: Model + Context + Git Status + Branch only
• Minimal: Model + Context only
• Custom: Pick individual segments

Configure during moai init / moai update wizard (answer "y" to reset statusline), or edit .moai/config/sections/statusline.yaml:

statusline:
  preset: compact  # or full, minimal, custom
  segments:
    model: true
    context: true
    output_style: false
    directory: false
    git_status: true
    claude_version: false
    moai_version: false
    git_branch: true

See SPEC-STATUSLINE-001 for details.

Q: What does the version indicator in statusline mean?

The MoAI statusline shows version information with update notifications:

🗿 v2.2.2 ⬆️ v2.2.5

• v2.2.2: Currently installed version
• ⬆️ v2.2.5: New version available for update

When you're on the latest version, only the version number is displayed:

🗿 v2.2.5

To update: Run moai update and the update notification will disappear.

Note: This is different from Claude Code's built-in version indicator (🔅 v2.1.38). The MoAI indicator tracks MoAI-ADK versions, while Claude Code shows its own version separately.

Q: "Allow external CLAUDE.md file imports?" warning appears

When opening a project, Claude Code may show a security prompt about external file imports:

External imports:
  /Users/<user>/.moai/config/sections/quality.yaml
  /Users/<user>/.moai/config/sections/user.yaml
  /Users/<user>/.moai/config/sections/language.yaml

Recommended action: Select "No, disable external imports" ✅

Why?

• Your project's .moai/config/sections/ already contains these files
• Project-specific settings take precedence over global settings
• The essential configuration is already embedded in CLAUDE.md text
• Disabling external imports is more secure and doesn't affect functionality

What are these files?

• quality.yaml: TRUST 5 framework and development methodology settings
• language.yaml: Language preferences (conversation, comments, commits)
• user.yaml: User name (optional, for Co-Authored-By attribution)

MoAI Memory

MoAI-ADK features a Git-Based Context Memory System that preserves AI-developer interaction context across sessions using structured git commit messages.

How It Works

Session 1 (Plan)          Session 2 (Run)           Session 3 (Sync)
    │                          │                          │
    ▼                          ▼                          ▼
 Decisions ──→ git commit ──→ Context ──→ git commit ──→ Context
 Constraints   with ## Context  loaded     with ## Context  loaded
 Patterns      section          from git   section          from git

Every implementation commit includes a structured ## Context section that captures:

Context Retrieval

# View context for a specific SPEC
/moai context --spec SPEC-AUTH-001

# Inject previous context into current session
/moai context --spec SPEC-AUTH-001 --inject

# Filter by category
/moai context --category Decision --days 7

Commit Format

Both DDD and TDD workflows produce structured commits:

DDD Mode:

🔴 ANALYZE: Document JWT validation behavior
SPEC: SPEC-AUTH-001
Phase: RUN-ANALYZE

## Context (AI-Developer Memory)
- Decision: Use EdDSA for JWT signing (performance priority)
- Constraint: Must support existing RSA tokens during migration

TDD Mode:

🔴 RED: Add failing test for token expiry validation
SPEC: SPEC-AUTH-001
Phase: RUN-RED

## Context (AI-Developer Memory)
- Decision: 15-minute access token TTL (security best practice)
- Gotcha: Clock skew between services requires 30s grace period

Key Benefits

• Zero Dependencies: Uses git itself as the memory store -- no external databases
• Team Sharing: Context travels with git clone -- automatic team knowledge transfer
• Full Audit Trail: git log provides complete decision history
• Session Continuity: Resume work with full context after /clear or session breaks

Contributing

Contributions are welcome! See CONTRIBUTING.md for detailed guidelines.

Quick Start

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. Ensure all tests pass: make test
5. Ensure linting passes: make lint
6. Format code: make fmt
7. Commit with conventional commit messages
8. Open a pull request

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

Community

• Issues -- Bug reports, feature requests

Star History

License

Copyleft 3.0 -- See the LICENSE file for details.

Links

• Official Documentation
• Claude Code