Configuration Sections Reference
Key configuration file keys in .moai/config/sections/ (handoff/delegation/llm/statusline/security/workflow/crosssession).
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.
InfoOne-line summary:settings.jsondefines what to allow Claude Code, while.moai/config/sections/*.yamldefines how MoAI-ADK orchestrates.
Controls how saved handoffs are handled across session boundaries.
handoff:
mode: manual # manual | auto
guide: false| Key | Value | Description |
|---|---|---|
mode | manual (default) | Do not auto-inject saved handoffs (opt-in baseline UX) |
mode | auto | Inject saved handoff into session context on /clear, then move to audit-trail copy |
guide | false (default) | When true, emit a best-effort stderr hint about a pending handoff on non-/clear session starts (startup/resume/compact). Informational only, does not block the session |
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]| Block | Description |
|---|---|
learning | Manages routing usage as an append-only ledger (.moai/state/routing-ledger.jsonl, opt-in·fail-open), and the harness learning subsystem proposes updates via a 4-tier ladder. auto_apply: false — Tier-4 changes require AskUserQuestion user approval |
subcommands | Per-subcommand agents (13 retained agents to spawn) + skills (workflow skills to inject at spawn). 0 assignments is valid (orchestrator executes directly) |
domain_skills | Skills to inject per mission domain (0-3 per spawn). Matched against domain signals |
agents | Per-agent conditional skills (loaded on-demand when trigger fires) |
Related: Agent Guide, Skill Guide.
Defines the harness backend, the GLM environment, and GLM model mappings. The model and effort that agents run on are decided at the session level — subagents inherit the main session’s model and effort — so this file no longer carries a per-agent model assignment. The former per-agent profile-matrix keys (profile, profiles, performance_tier, harness_agents, agent_overrides) are retired; moai update strips them from user files on the next run. Main-session reasoning effort comes from the preference profile (moai profile setup), never from this file.
llm:
harness: "claude" # claude | gpt | both — agent harness selected at init time
team_mode: "" # glm switches the backend to z.ai
glm_env_var: "GLM_API_KEY"
glm:
base_url: "https://api.z.ai/api/anthropic"
models:
high: "glm-5.3-flash" # 1M context — Opus slot
medium: "glm-5.3-flash" # 1M context — Sonnet slot
low: "glm-5.3-flash" # 1M context — lightweight slot
fable: "glm-5.3-flash"| Key | Description |
|---|---|
harness | The agent harness deployed at init (claude default; gpt means Codex-only deployment) |
team_mode | Empty runs Claude; glm routes the session to the z.ai backend |
claude_bin | Optional explicit Claude Code binary pin (environment variable MOAI_CLAUDE_BIN overrides per launch) |
glm.base_url | Z.AI Anthropic-compatible proxy endpoint |
glm.models | Per-slot GLM model mapping. GLM collapses Claude’s 5-step effort into 3 reasoning states (thinking-off / reasoning-high / reasoning-max) |
Related: Profile Matrix, 3-Tier Agent Architecture.
Controls the statusline theme, which hosting service the github segment counts against, and 16 segment toggles.
statusline:
theme: "catppuccin-mocha" # catppuccin-mocha | catppuccin-latte
# forge: gitlab # github | gitlab | none (unset detects from the origin host)
segments:
model: true
context: true
# ... 16 segments total (all on by default)
task: true
pr: true| Key | Description |
|---|---|
theme | Exactly 2 themes exist: catppuccin-mocha (default) or catppuccin-latte |
forge | One of github · gitlab · none — which hosting service the github segment counts open work against. Leave it unset and the value is decided from the origin remote’s host: github.com selects gh, gitlab.com selects glab. A self-hosted instance carries no signal in its name, so set it explicitly there. An unrecognised value renders nothing rather than falling back to detection, so a typo shows as an absent segment instead of a wrong count |
segments | 16 individual segment toggles (the only runtime lever). All on by default; inactive states are handled gracefully with no output |
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'
extra_deny_patterns: []
extra_ask_patterns: []
permission:
strict_mode: true
session_rules: []
sandbox:
required: false
network_allowlist: []
env_scrub_extra: []
docker_image: "alpine:latest"| Key | Description |
|---|---|
extra_dangerous_bash_patterns | Additional dangerous Bash command regex patterns (case-insensitive) added to built-in deny patterns |
extra_deny_patterns / extra_ask_patterns | Additional file deny/ask patterns |
permission.strict_mode | When true, rejects agent spawns in bypassPermissions mode |
sandbox.required | When true, rejects sandbox: none agents without sandbox.justification (default false) |
sandbox.network_allowlist | Network hosts added to the default 8 hosts |
sandbox.env_scrub_extra | Env variable names added to default scrub list (AWS_*, GITHUB_TOKEN, etc.) |
sandbox.docker_image | Default image for docker backend |
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| Key | Value | Description |
|---|---|---|
enabled | false (default) | The guard is fully inert. It does not even run the git rev-parse needed to classify the checkout, so it costs nothing |
enabled | true | Branch-state-changing commands are refused in the primary checkout. Inside a worktree they are allowed as before |
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.
At session start MoAI shows an advisory about SPEC lifecycle drift. Computing it takes about a second — far longer than a session start can wait — so the result is cached against the current commit. Once the commit changes, the cached result no longer matches and the advisory has nothing to show.
With this key enabled, the session-start handler starts one short-lived background process on that miss, computes the drift there, and returns immediately without waiting for it. The next session reads the stored result and shows the advisory again.
workflow:
drift_cache_fill:
enabled: true # distributed default| Key | Value | Description |
|---|---|---|
enabled | true (default) | On a cache miss the handler starts one background fill and returns without waiting. The advisory reappears on the following session |
enabled | false | No fill process is ever started. The advisory resolves from whatever the cache already holds, so after a commit it stays absent until something else fills the cache |
Why this one ships on. The other guards on this page ship off because they are inert until a maintainer needs them. This key is not inert when on — it starts a child process — so its default is an accepted cost rather than a neutral one: without the fill, the drift advisory never returns after a commit. The child is short-lived, bounded by its own deadline, limited to one at a time by a lock, and silent.
Failure direction. Every failure path leaves the session untouched. If the child cannot start, cannot finish, or writes nothing, the handler has already returned and the advisory simply stays as it was — a failed fill never delays or breaks a session start.
Pins which model and effort the cross-model audit backends (codex_audit, glm_audit, audit_multi) actually run on. Each backend takes one {model, effort} pair, and the distributed defaults are empty.
workflow:
audit:
codex:
model: "" # e.g. gpt-6.1-terra — a codex-servable model id
effort: "" # e.g. xhigh — none | low | medium | high | xhigh | max
glm:
model: "" # e.g. glm-5.3
effort: "" # e.g. max — low | high | max (z.ai reasoning-state names)| Key | Description |
|---|---|
audit.codex.{model, effort} | The pair the codex audit carries on session start and review turns. An empty model, or one codex cannot serve, discards the pin and falls back to the existing SSOT resolution |
audit.glm.{model, effort} | The pair the GLM audit carries on the z.ai request. Effort accepts only the z.ai reasoning-state names low, high, max; any other value drops the reasoning directive while the model pin still applies |
| Both pairs empty | The resolvers behave exactly as before this key existed — a project that never writes a pin changes nothing |
The pin applies to the audit entry points only. Model resolution on the task-delegation paths (codex_task, glm_task) is unaffected, and the same fields are editable in the web console’s Audit panel.
The switch that turns the backlog queue’s guidance surfaces off. The session-start summary line, the statusline TODO segment, and the skill’s inference routing of natural-language requests into the todo workflow — all three go quiet under this one key.
workflow:
todo:
enabled: false # explicit off — an absent key reads as on| Key | Value | Meaning |
|---|---|---|
todo.enabled | (key absent, default) | On. The shipped template carries no todo block at all, which is the state most projects live in |
todo.enabled | false | The session-start summary, the statusline TODO segment, and the skill’s automatic routing turn off |
Turning it off does not remove the command. The moai todo CLI stays registered with every verb working, and an explicit /moai todo invocation still runs. That boundary is intended — the switch silences only the surfaces that show the queue to someone who did not ask for it, and leaves the path of someone actually using it untouched. A config file that cannot be read also resolves to on (fail-open).
Reach for this key when the per-session backlog summary reads as noise on a small, one-off project. How to operate the queue itself is on the moai todo page.
Sets how a SPEC’s autonomy contract (contract.yaml) is signed and bounded. The command that works with contracts is moai contract. Despite the similar name, this is unrelated to the autonomy tier (MOAI_AUTONOMY_TIER).
workflow:
autonomy:
mode: guided # guided | contract
contract:
batch_sign: false # sign several SPECs with one confirmation
second_review: required # required | advisory | off
push_develop: false # allow the push-develop action in contracts
kickoff:
# decider: human | llm | llm+jev (omitted: human in guided, llm in contract)
jev_min_confidence: 0.50
escalation:
budget_default: { turns: 60, operations: 40, audit_retries: 2 }| Key | Description |
|---|---|
mode | guided (default) or contract. Receipt-based signing (--signer llm) is open only in contract |
contract.batch_sign | When true, several SPECs are signed with one confirmation. Default false |
contract.second_review | required makes a contract invalid when its review.second_model is none or empty. advisory and off skip this check |
contract.push_develop | When false (default), a contract containing the push-develop action is invalid |
kickoff.decider | Who makes the kickoff decision: human, llm, or llm+jev. Derived from the mode when omitted. jev alone is a configuration error, and receipt signing is refused |
kickoff.jev_min_confidence | Reserved for the kickoff receipt issuer as the minimum confidence at which it accepts a Jev judgment. In this release the value is only read and validated; it does not affect signing or verification. Default 0.50 |
escalation.budget_default | Default budget filled in at signing time when a contract has no budget |
Invalid values. An absent key takes the default above. An unrecognized value for mode, second_review, decider, or jev_min_confidence falls back to the stricter default (guided, required, human, 0.50), with a warning naming the key.
Decides how this session treats messages from your other Claude Code sessions. The moai cc · moai glm launchers translate these values into a transient --settings file at launch, and the web console edits this file through the settings seam. A session launched without the launcher — a bare claude command — does not read this file.
crosssession:
inbound: "" # "" | accept | hold | refuse
isolate_machines: false # default — no approval required before a message leaves this machine
dialog_expiry: "" # "" | 60s | 5m | 10m | never| Key | Value | Description |
|---|---|---|
inbound | "" (default) | Claude Code decides per message from the two sessions’ permission-mode classes |
inbound | accept | Delivers the message. A worker session meant to take messages unattended needs this value |
inbound | hold | Parks each message for approval. A message held this way does not expire; it is delivered when an accept later applies |
inbound | refuse | Drops the message |
isolate_machines | false (default) | No approval is required before a message goes to a session beyond this machine. Messages between sessions on the same machine never leave the machine whatever the value is, but a message to a session beyond it travels through Anthropic servers — so the default permits that path without asking. Decide whether to keep it rather than inheriting it unread |
isolate_machines | true | Requires your explicit approval before any message leaves the machine, even in bypassPermissions mode. A true from ANY settings scope applies, so a checked-in project file can turn the requirement on but not off — turning it off means removing the true from every scope that sets it |
dialog_expiry | "" (default) | Keeps Claude Code’s five-minute default |
dialog_expiry | 60s · 5m · 10m · never | Deadline for the approval dialog on a default-held message; never holds until the session ends. It does not apply to a message held by an explicit inbound: hold |
- settings.json Guide — Claude Code runtime settings
- Harness Profiles & Evaluation — harness.yaml / evaluator-profiles
- moai doctor —
moai doctor configfor merged configuration inspection