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

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

• 38,700+ lines of Go code, 38 packages
• 85-100% test coverage
• 26 specialized AI agents + 47 skills
• 18 programming languages supported
• 27 Claude Code hook events

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.

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

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

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.

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

Prebuilt binaries are available on the Releases page.

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.

moai init my-project

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

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

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

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.

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.

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:

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

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

    M --> MG["📋 Manager (8)"]
    M --> EX["⚡ Expert (8)"]
    M --> BL["🔧 Builder (3)"]
    M --> EV["🔍 Evaluator (2)"]
    M --> AG["🎨 Agency (6)"]

    MG --> MG1["spec · ddd · tdd · docs<br/>quality · project · strategy · git"]
    EX --> EX1["backend · frontend · security · devops<br/>performance · debug · testing · refactoring"]
    BL --> BL1["agent · skill · plugin"]
    EV --> EV1["evaluator-active · plan-auditor"]
    AG --> AG1["planner · copywriter · designer<br/>builder · evaluator · learner"]

    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 EV fill:#FF5722,color:#fff
    style AG fill:#FF9800,color:#fff

Total: 27 agents

Note: Dynamic team teammates (researcher, analyst, architect, implementer, tester, designer, reviewer) are spawned at runtime via role profiles, not as static agent definitions.

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

MoAI-ADK assigns optimal AI models to each of 24 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.

# 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).

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

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

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'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

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.

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

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.

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

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

Every code change is validated against five quality criteria:

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.

All hook events follow the Claude Code hooks protocol with JSON stdin/stdout communication:

• 27 event types: SessionStart, PreToolUse, PostToolUse, SessionEnd, Stop, SubagentStop, PreCompact, PostCompact, PostToolUseFailure, Notification, SubagentStart, UserPromptSubmit, PermissionRequest, PermissionDenied, TeammateIdle, TaskCompleted, TaskCreated, WorktreeCreate, WorktreeRemove, InstructionsLoaded, StopFailure, ConfigChange, CwdChanged, FileChanged, Elicitation, ElicitationResult, Setup
• 4 hook types: command (shell scripts), prompt (LLM evaluation), agent (subagent verification), http (webhook endpoints)
• Smart behaviors: PermissionDenied auto-retry for read-only tools, StopFailure error-type responses, PostCompact session memo restoration, SubagentStart context injection
• Matchers: Event-specific filtering (tool name, session source, error type, config source)
• CLAUDE_ENV_FILE: Environment variable persistence via CwdChanged/FileChanged hooks

MoAI-ADK supports z.ai GLM as an alternative AI backend for Claude Code, enabling multi-LLM development workflows.

Default Model Mapping:

Free models also available: GLM-4.7-Flash, GLM-4.5-Flash. See z.ai Pricing for full details.

Sign up for GLM Coding Plan

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.

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
    │
    └── 4. Launch Claude Code (replaces current process)

┌─────────────────────────────────────────────────────────────┐
│  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                  │
└─────────────────────────────────────────────────────────────┘

# 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. Launch CG mode (automatically starts Claude Code)
moai cg

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

Agent Teams supports two display modes:

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

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

@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() {
        // ...
    }()
}

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.

// ❌ 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) {
    // ...
}

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

# 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

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

Just describe what you want. Agency interviews you, designs, builds, tests, and learns — autonomously.

MoAI-ADK includes AI Agency — a specialized harness for autonomous website and web application production. Like /moai "description" runs the full development workflow, /agency "description" runs the full creative production pipeline from brief to deployed code.

flowchart TB
    subgraph MOAI["/moai — General Software Development"]
        direction LR
        M1["📋 Plan<br>(SPEC)"] --> M2["⚙️ Run<br>(DDD/TDD)"] --> M3["📦 Sync<br>(Docs + PR)"]
    end

    subgraph AGENCY["/agency — Creative Web Production"]
        direction LR
        A1["📋 Planner<br>(BRIEF)"] --> A2["✍️ Copywriter"]
        A1 --> A3["🎨 Designer"]
        A2 --> A4["🔨 Builder"]
        A3 --> A4
        A4 --> A5["🔍 Evaluator"]
        A5 -->|"FAIL"| A4
        A5 -->|"PASS"| A6["🧠 Learner"]
    end

    style MOAI fill:#e8f5e9,stroke:#4caf50
    style AGENCY fill:#fff3e0,stroke:#ff9800

When to use which:

• Building a REST API, CLI tool, or library? → /moai
• Building a marketing website, SaaS landing page, or web app with design? → /agency
• Need copy, design tokens, and code as separate artifacts? → /agency

/agency "SaaS landing page for my AI developer tools startup"

This single command triggers the entire autonomous workflow:

1. Client Interview — Agency asks 9 structured questions about your business, brand, and tech preferences (skipped if already configured)
2. BRIEF Generation — Planner expands your request into a comprehensive project brief
3. Copy + Design — Copywriter produces brand-aligned marketing copy; Designer creates a full design system with tokens
4. Code Implementation — Builder implements production code using TDD (Next.js + Tailwind by default)
5. Quality Assurance — Evaluator runs Playwright tests, Lighthouse audits, and 4-dimension scoring
6. GAN Loop — If quality fails, Builder and Evaluator iterate (up to 5 rounds) until threshold is met
7. Self-Learning — Learner detects patterns from the session and proposes skill improvements

Typical duration: 15-45 minutes for a complete landing page, fully autonomous.

flowchart LR
    REQ["🎯 /agency 'request'"] --> INT["📋 Client Interview"]
    INT --> P["📝 Planner (BRIEF)"]
    P --> C["✍️ Copywriter"]
    P --> D["🎨 Designer"]
    C --> B["🔨 Builder (TDD)"]
    D --> B
    B --> E["🔍 Evaluator"]
    E -->|"FAIL (max 5 rounds)"| B
    E -->|"PASS (score ≥ 0.75)"| L["🧠 Learner"]

The Evaluator is skeptical by default — tuned to find defects, not rationalize acceptance.

sequenceDiagram
    participant B as 🔨 Builder
    participant E as 🔍 Evaluator
    participant U as 👤 User

    B->>E: Submit code (iteration 1)
    E->>E: Score 4 dimensions
    E-->>B: ❌ FAIL (0.58) — feedback with file:line refs

    B->>E: Revised code (iteration 2)
    E->>E: Score 4 dimensions
    E-->>B: ❌ FAIL (0.67) — mobile viewport + copy mismatch

    B->>E: Revised code (iteration 3)
    E->>E: Score 4 dimensions
    Note over E: Stagnation detected (improvement < 0.05)
    E-->>U: ⚠️ Escalation — 3 rounds without pass

    alt User adjusts criteria
        U-->>E: Lower threshold to 0.65
        E-->>B: ✅ PASS (0.67)
    else User provides guidance
        U-->>B: Fix specific layout issue
        B->>E: Revised code (iteration 4)
        E-->>B: ✅ PASS (0.78)
    end

Scoring dimensions (must-pass threshold: 0.75):

Iteration flow: Evaluator provides specific feedback with file:line references → Builder fixes → re-evaluation. After 3 failed iterations, escalates to user with options: adjust criteria, provide guidance, or force-pass.

On first run, Agency conducts a structured client interview (9 questions across 4 phases):

Brand context flows through every agent as an immutable constraint. The Evaluator scores brand consistency as a must-pass criterion. After 5+ projects, the interview adapts to ask only 3 key questions.

Every skill has Static + Dynamic zones:

• Static Zone: Core principles (never auto-modified)
• Dynamic Zone: Rules, heuristics, anti-patterns (evolved via Learner)

flowchart LR
    subgraph Observation["📊 Pattern Detection"]
        O1["1x seen"] -->|"Logged"| O2["3x seen"]
        O2 -->|"Promoted"| O3["5x seen"]
    end

    subgraph Graduation["🎓 Knowledge Graduation"]
        O3 -->|"confidence ≥ 0.80"| G1["Canary Check"]
        G1 -->|"No score drop"| G2["Contradiction Check"]
        G2 -->|"No conflicts"| G3["👤 Human Review"]
        G3 -->|"Approved"| G4["✅ Graduated"]
    end

    subgraph Safety["🛡️ Safety Gates"]
        G4 --> S1["Verify in next project"]
        S1 -->|"Score drops > 0.10"| S2["🔄 Auto-Rollback"]
    end

    style Observation fill:#e3f2fd,stroke:#1976d2
    style Graduation fill:#f3e5f5,stroke:#7b1fa2
    style Safety fill:#fce4ec,stroke:#c62828

Knowledge Graduation lifecycle: observation (1x) → heuristic (3x) → rule (5x, confidence ≥ 0.80) → graduated (applied with user approval)

5-Layer Safety Architecture:

1. Frozen Guard — Blocks modification of identity, safety rails, and ethical boundaries
2. Canary Check — Shadow-evaluates last 3 projects; rejects if any score drops > 0.10
3. Contradiction Detector — Flags rules that conflict with existing ones
4. Rate Limiter — Max 3 evolutions/week, 24h cooldown, max 50 active learnings
5. Human Oversight — Presents before/after diff with evidence; requires user approval

Anti-Pattern Protection: A single critical failure (score drop > 0.20) triggers immediate Anti-Pattern classification — the pattern is FROZEN and can never be evolved away. Only human intervention can reclassify.

# Autonomous workflow (recommended)
/agency "SaaS landing page for my AI startup"  # Full pipeline: interview → build → test → learn

# Step-by-step workflow
/agency brief "landing page for dev tools"    # Interview + BRIEF only (review before building)
/agency build BRIEF-001                       # Run full pipeline from existing BRIEF
/agency build BRIEF-001 --step                # Approve each phase before proceeding

# Quality & review
/agency review BRIEF-001                      # Re-run evaluator on existing build
/agency phase BRIEF-001 copywriter            # Re-run specific phase only

# Self-evolution
/agency learn                                 # Record feedback for pattern detection
/agency evolve                                # Graduate learnings to skill rules
/agency evolve --agent copywriter             # Evolve specific agent only

# Session & profile
/agency resume BRIEF-001                      # Resume interrupted workflow
/agency profile                               # View adaptation stats and evolution history

# System management
/agency sync-upstream                         # Sync forked agents with MoAI updates
/agency rollback agency-copywriting           # Rollback skill to previous version
/agency config                                # View/edit pipeline configuration

Agency Documentation

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.

The statusline v3 features a multi-line layout with real-time API usage monitoring:

Full mode (5 lines — 40-block individual bars):

🤖 Opus 4.6 │ 🔅 v2.1.74 │ 🗿 v2.7.12 │ ⏳ 5h 32m │ 💬 MoAI
CW: 🔋 █████████████████████░░░░░░░░░░░░░░░░░░░ 52%
5H: 🔋 █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 4%
7D: 🔋 ██████████████████████░░░░░░░░░░░░░░░░░░░ 56%
📁 moai-adk-go │ 🔀 main │ 📊 +0 M38 ?2

Default mode (3 lines — 10-block inline bars):

🤖 Opus 4.6 │ 🔅 v2.1.74 │ 🗿 v2.7.12 │ ⏳ 16m │ 💬 MoAI
CW: 🔋 ██░░░░░░░░ 25% │ 5H: 🔋 █░░░░░░░░░ 12% │ 7D: 🔋 ░░░░░░░░░░ 3%
📁 moai-adk-go │ 🔀 fix/my-feature │ 📊 +0 M38 ?2

2 display modes are available:

• Full (5 lines): All segments with individual 40-block usage bars per line (model, context, usage bars, git, version, output style, directory)
• Default (3 lines): Core segments with inline 10-block usage bars (model, context, usage bars, git status, branch, version)

Edit .moai/config/sections/statusline.yaml directly:

statusline:
  preset: default  # or full
  segments:
    model: true
    context: true
    usage_5h: true    # 5-hour API usage bar
    usage_7d: true    # 7-day API usage bar
    output_style: true
    directory: true
    git_status: true
    claude_version: true
    moai_version: true
    git_branch: true

Note: As of v2.7.8, segment preset selection has been removed from the moai init/moai update wizard. Configure segments directly in the YAML file above.

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.

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)

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

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

• Issues -- Bug reports, feature requests

Apache License 2.0 -- See the LICENSE file for details.

• Official Documentation
• Claude Code