moai-adk

Supports Claude Code

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
/moai github issues                      # Fix GitHub issues with Agent Teams
/moai github pr 123                       # Review PR with multi-perspective analysis

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

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

Evaluator Agents

Builder Agents

Anthropic Built-in

Team Role Profiles (dynamic, not static agents)

Team role profiles (researcher, analyst, architect, implementer, tester, designer, reviewer) are spawned dynamically at runtime via Agent(subagent_type: "general-purpose") with model + isolation overrides from workflow.yaml. They are NOT static agent definitions and do not have fixed tier-mapping rows.

Configuration

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

# Reconfigure existing project
moai update -c                # Re-run the init wizard (no template sync)

moai update vs moai update -c: bare moai update syncs templates via 3-way merge; moai update -c (--config) re-runs the init wizard to edit project configuration and does NOT synchronize templates.

During moai update -c, 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).

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

Harness v4 Architecture: See SPEC-V3R6-HARNESS-V4-001 and .claude/skills/moai/workflows/harness-builder.md for the orchestrator-direct Builder workflow, manifest.json schema, Runner primitive mapping, and conditional worktree isolation rules.