moai-adk

---

📚 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. 8 retained AI agents (7 MoAI-custom + 1 Anthropic built-in Explore) and 27 moai-* template-managed 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

• 100K+ lines of Go code across 100+ packages
• 85-100% test coverage
• 8 retained AI agents + 27 moai-* skills (template-managed; excludes 2 harness-moaiadk-* user-owned)
• 16 programming languages supported
• 27 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.

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.

---

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
/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 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 8 retained agents.

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

    M --> MS["📋 manager-spec"]
    M --> MD["🔨 manager-develop"]
    M --> MDoc["📄 manager-docs"]
    M --> MG["🌿 manager-git"]
    M --> PA["🔍 plan-auditor"]
    M --> SA["⚖️ sync-auditor"]
    M --> BH["🔧 builder-harness"]
    M --> EX["👁️ Explore (built-in)"]

    style M fill:#FF6B35,color:#fff
    style MS fill:#4CAF50,color:#fff
    style MD fill:#2196F3,color:#fff
    style MDoc fill:#2196F3,color:#fff
    style MG fill:#2196F3,color:#fff
    style PA fill:#FF5722,color:#fff
    style SA fill:#FF5722,color:#fff
    style BH fill:#9C27B0,color:#fff
    style EX fill:#607D8B,color:#fff

Agent Categories

Total: 8 retained agents (7 MoAI-custom + 1 Anthropic built-in Explore)

12 legacy agent names (e.g. manager-strategy, manager-quality, manager-project, the 6 expert-* agents) are archived and MUST NOT be spawned. When a paste-ready resume or Agent() invocation references an archived name, the orchestrator rejects the spawn and consults the migration table at .claude/rules/moai/workflow/archived-agent-rejection.md.

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

/moai Slash Commands (13)

MoAI exposes 13 /moai slash commands in .claude/commands/moai/, managed through a 3-level progressive disclosure system for token efficiency (skill metadata is always listed; bodies load on invocation; bundled references load on demand).

The full command set (13 total): clean · codemaps · feedback · fix · gate · harness · loop · mx · plan · project · review · run · sync.

---

Model Policy (Token Optimization)

MoAI-ADK assigns optimal AI models to each of the 8 retained 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

Only the 8 retained agents appear below. 12 legacy agent names are archived — for the migration table of manager-strategy, manager-quality, manager-project, the 6 expert-* agents, and others, see .claude/rules/moai/workflow/archived-agent-rejection.md.

Manager Agents

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

---

Decision Memory

MoAI-ADK now captures your AskUserQuestion decisions and uses them to personalize future recommendations. This system learns from your choices while maintaining privacy through automatic data decay and session-scoped controls.

5 Components

1. 3-Tier Memory Layer (internal/cli/preference/)

   • Core: Hot preferences (≤4KB) for instant access
   • Recall: Recent session data with weight-based decay
   • Archival: Long-term storage with soft-delete after 28 days

2. Adaptive Recommendation Placement (.claude/rules/moai/core/askuser-protocol.md)

   • Questions are asked when uncertainty is highest (Fisher information p≈0.5)
   • Recommendations are based on statistical majority, not system defaults
   • Expert users receive weaker (info-centric) guidance
   • Cold-start preferences disclose "based on static default, N observations needed for personalization"

3. PostToolUse Capture Hook (internal/hook/user_decision_capture.go)

   • Advisory/fail-open design — never blocks AskUserQuestion execution
   • Captures observed confidence with session-level source citation
   • Schema-tolerant parsing handles multiple payload formats
   • Recovery-Signal Carve-Out: advisory on recovery turns (doctrine-honest, per REQ-ADM-010)

4. Decay Policy (moai preference decay-scan)

   • Power-law weight function: (age+1)^(-0.5) — α=0.5 fixed for Standard tier
   • 28-day TTL for transient preferences (stable preferences preserved)
   • Touch reset-on-reuse: using a preference refreshes its weight to 1.0
   • Daily scan cadence with 24h gate (idempotent, cross-process safe)

5. Recovery Controls

   • Session-scoped toggle (moai preference toggle — disable per project)
   • Sensitive-domain gate — reduces recommendation strength for security/vulnerability topics
   • Proficiency estimator — cold-start (<5 sessions) / general (5-19) / expert (20+)
   • Freshness disclosure — "based on N-day-old data" transparency
   • Correction loop — observed facts override inferences with archival audit trail

Usage

# View captured preferences
moai preference list [--domain=<D>] [--key=<K>]

# Trigger decay scan (runs daily via cron/automation)
moai preference decay-scan [--memory-dir=<path>] [--now=<timestamp>] [--force]

# Toggle personalization (session-scoped)
moai preference toggle [--disable] [--project-root=<path>]

Privacy & Safety

• Namespace separation: User decisions stored in memory/user_decisions/, separate from engineering lessons
• Advisory capture: Hook never blocks AskUserQuestion; all errors fail-open
• Automatic decay: Transient entries soft-delete after 28 days; stable entries (explicitly marked) preserved
• Session control: Toggle is per-project, non-persistent across sessions (automatic re-activation on new sessions)
• Sensitive domains: Security-related topics receive neutral recommendations with disclosure logging

See SPEC-V3R6-ASKUSER-DECISION-MEMORY-001 for complete requirements, architecture, and acceptance criteria.

---

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/>Agent(name=…) → 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 Agent(name=…) (implicit team), 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

3-phase lifecycle (V3R6): MoAI's lifecycle is exactly three phases — plan → run → sync. The former fourth "Mx-phase" was retired per SPEC-V3R6-LIFECYCLE-REDESIGN-001; MX Tag validation is now a cross-cutting sync concern, not a separate phase. Dynamic workflows (/effort ultracode, Claude Code v2.1.154+) are available as an optional fan-out primitive within the run phase.

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

Hook Protocol (v2.10.1)

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

---

CLI Commands

---

Claude x GLM Multi-LLM

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

Default Model Mapping:

All four Claude tiers (Opus, Sonnet, Haiku, Fable) are unified to glm-5.2[1m] — a single 1M-context model. GLM models are intentionally NOT mapped disparately across these slots (e.g. opus→glm-5.2, sonnet→glm-4.7, haiku→glm-4.5-air) because mixing a 1M-context model with 200K-context models across those slots breaks agent-spawn session sharing: a 1M-context model and a 200K-context model cannot share a session.

The [1m] suffix on glm-5.2[1m] activates Claude Code's 1M-token context mode. Claude Code parses and strips the suffix before the upstream z.ai API call, so z.ai never sees it.

The mapping is implemented via four Claude Code ANTHROPIC_DEFAULT_*_MODEL environment variables — ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, and ANTHROPIC_DEFAULT_FABLE_MODEL — all set to glm-5.2. The Fable variable is officially supported as of Claude Code v2.1.202.

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

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

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

---

---

Database schema tooling: database-schema synchronization is handled by the CLI hook moai hook db-schema-sync (see the CLI reference), not a dedicated slash command.

---

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 v3 features a multi-line layout with real-time API usage monitoring:

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

🤖 Opus 4.7 │ 🔅 v2.1.170 │ 🗿 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.7 │ 🔅 v2.1.170 │ 🗿 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:
  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: The preset shorthand (full/compact/minimal) has been retired — configure the segment map directly above. A legacy preset: key in an existing config is silently ignored by the loader. Segment selection was already removed from the moai init/moai update wizard as of v2.7.8.

---

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)

---

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

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

Links

• Official Documentation
• Claude Code