Frequently Asked Questions

Frequently asked questions and answers about using MoAI-ADK.

They are two completely different things. This is the most common confusion, so let’s clear it up first.

• Running moai plan in the terminal does nothing — /moai plan is only valid inside Claude Code.
• Typing /moai init in Claude Code does nothing — moai init is a terminal command.

The MoAI statusline shows version information together with an update notification:

🗿 v3.1.2 -> 🗿 v3.1.3

• 🗿 v3.1.2: The currently installed version
• -> 🗿 v3.1.3: A newer version available for update, joined by the ASCII arrow ->

When you are on the latest version, only the version number is shown:

🗿 v3.1.3

How to update: Run moai update and the update notification disappears.

Info

Note: This is different from Claude Code’s built-in version display (🔅 v2.1.172). The MoAI display tracks the MoAI-ADK version, while Claude Code displays its own version separately.

The statusline is toggled one segment at a time. Turn each segment on or off to keep only the information you want. There are no display presets — the configuration is just a theme and a set of segments.

Configure it in the moai init or moai update -c wizard, or edit .moai/config/sections/statusline.yaml directly:

statusline:
  segments:
    model: true
    context: true
    output_style: false
    directory: false
    git_status: true
    claude_version: false
    moai_version: false
    git_branch: true

With no segments: block, every segment is enabled by default.

Info

For details, see SPEC-STATUSLINE-001.

MoAI-ADK assigns the optimal AI model to each agent according to your Claude Code subscription plan. It is a tokenomics mechanism that maximizes quality within your plan’s usage limits.

Warning

Why does this matter? Lowering the tier lowers reasoning depth, not model class. On a long-horizon agentic task, Opus at low effort scores higher and costs less per task than Sonnet at any effort — the bill is set by how many steps a model spends finishing, not by the per-token rate. So low economizes within Opus and reaches for Sonnet only on single-shot rows (manager-git, Explore) where multi-step completion failure does not apply.

Of the 11-agent catalog (10 MoAI custom + 1 Anthropic built-in Explore), the MoAI custom agents are assigned models according to the tier. The 12 archived agents from earlier versions are not available.

The built-in Explore resolves to sonnet / low in every column — a call-time default, since it has no agent file on disk to pin.

# During project initialization
moai init my-project          # Select the model policy in the interactive wizard

# Reconfigure an existing project
moai update -c                # Re-run the setup wizard

Info

The default tier is medium. Change it by re-running the setup wizard with moai update -c.

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

Info

Recommended action: Choose “No, disable external imports”.

Why:

• These files already exist in your project’s .moai/config/sections/
• Project-level settings take precedence over global settings
• The essential settings are already included in the CLAUDE.md text
• Disabling external imports is safer and does not affect functionality

What the files are:

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

MoAI-ADK v2.5.0+ lets you choose between two methodologies (TDD or DDD only). The hybrid mode was removed for clarity and consistency.

TDD writes the test first and then makes it pass, which suits new development; DDD pins existing behavior down with characterization tests and then works on it in small steps, which suits code that has almost no tests. The step-by-step procedure for each cycle is covered in SPEC-Based Development and DDD.

# Auto-detected during project initialization
moai init my-project          # Can be specified with the --mode <ddd|tdd> flag

# Manual configuration
# Edit .moai/config/sections/quality.yaml
development_mode: tdd         # or ddd

This is completely normal. The @MX tag system is designed to mark only the most dangerous and important code the AI should look at first.

To scan your codebase for @MX tags:

/moai mx --all        # Full scan
/moai mx --dry        # Preview
/moai mx --priority P1  # Critical items only

• GitHub Discussions — Questions, ideas, feedback
• Issues — Bug reports, feature requests
• Discord Community — Real-time chat, tips