Configuration Sections Reference

MoAI-ADK project settings are split into several YAML files under .moai/config/sections/. While the settings.json guide covers Claude Code runtime settings, this page documents the keys of the main section files that control MoAI-ADK’s own behavior.

Info

One-line summary: settings.json defines what to allow Claude Code, while .moai/config/sections/*.yaml defines how MoAI-ADK orchestrates.

Controls how saved handoffs are handled across session boundaries.

handoff:
    mode: manual   # manual | auto
    guide: false

Related: Autonomous Continuation Loops, moai handoff.

This is the default skill/agent assignment map per /moai subcommand. When orchestrator builds an execution plan (Analyze-First), it reads this map to decide which agents to spawn and which skills to inject.

delegation:
    version: 1
    learning:
        observe: routing-ledger
        propose_via: harness-tier-ladder
        auto_apply: false          # Tier-4 gate — requires user approval
    subcommands:
        plan:
            agents: [manager-spec, plan-auditor, Explore]
            skills: [moai-workflow-spec, moai-foundation-thinking]
        # run / sync / project / fix / loop / ...
    domain_skills:
        backend:  [moai-ref-api-patterns, moai-domain-backend]
        security: [moai-ref-owasp-checklist, moai-ref-llm-security, ...]
    agents:
        manager-spec: [moai-workflow-spec, moai-foundation-thinking]

Related: Agent Guide, Skill Guide.

Defines the profile, the profile matrix, per-agent overrides, and GLM model mappings.

llm:
  profile: "medium"            # high | medium | low (active matrix column; max read as high)
  performance_tier: "medium"   # legacy alias (read when profile absent; same vocabulary)
  profiles:                    # profile column → 11 agents → {model, effort}
    high: { ... }              # detailed table: Profile Matrix page
    medium: { ... }
    low: { ... }
  agent_overrides: {}          # per-agent {model, effort} override (optional)
  glm:
    base_url: "https://api.z.ai/api/anthropic"
    models:
      high: "glm-5.3"          # 1M context — Opus slot
      medium: "glm-5.3"        # 1M context   — Sonnet slot
      low: "glm-5.3"          # 1M context   — lightweight slot
      fable: "glm-5.3"

Related: Profile Matrix, 3-Tier Agent Architecture.

Controls statusline theme and 16 segment toggles.

statusline:
  theme: "catppuccin-mocha"   # catppuccin-mocha | catppuccin-latte
  segments:
    model: true
    context: true
    # ... 16 segments total (all on by default)
    task: true
    pr: true

Segments are placed across 3 lines — line 1 (model·version·session meta), line 2 (context window·API usage bar), line 3 (directory·git·workflow·PR).

Related: Statusline System & PR Segment.

Additional security settings that extend (not replace) the built-in DefaultSecurityPolicy pattern. Follows SOLID’s open-closed principle — config-only extension without core modifications.

security:
  extra_dangerous_bash_patterns:
    - 'curl\s+.*\|\s*(ba)?sh'
    - 'rm\s+-rf\s+/[^.]'
  extra_deny_patterns: []
  extra_ask_patterns: []
  permission:
    strict_mode: true
    session_rules: []
  sandbox:
    required: false
    network_allowlist: []
    env_scrub_extra: []
    docker_image: "alpine:latest"

Related: Security Notes, settings.json Guide.

An opt-in guard that protects branch state in the primary checkout. When several sessions share one checkout, a git switch, git checkout, git reset --hard, git stash or git rebase run by one of them changes another session’s working tree with no signal to either side. This guard refuses those commands, and only in the primary checkout.

workflow:
    branch_guard:
        enabled: false   # distributed default

Why it ships off. The hazard this guard addresses only exists when several sessions share one checkout. It does not arise in a single-developer repository, so the distributed build ships with the guard disabled. A maintainer running several sessions at once writes the key above to turn it on.

Scope. The guard distinguishes the primary checkout from a worktree and does not block branch operations inside a worktree. Read-only commands such as git status, git log, git diff and git fetch, along with git stash list and git merge-base, pass even while it is enabled.

Exemptions and failure direction. The git agent that has to create branches is exempted by identity, and the MOAI_BRANCH_GUARD_EXEMPT=1 environment variable also bypasses it. When classification is uncertain (not a git repository, git rev-parse failing, and so on) the command is allowed through and only an audit-log entry is written — the guard refuses only on positive evidence.

Work that needs a different branch belongs in a worktree rather than behind a refusal. For the procedure see moai worktree.

• settings.json Guide — Claude Code runtime settings
• Harness Profiles & Evaluation — harness.yaml / evaluator-profiles
• moai doctor — moai doctor config for merged configuration inspection