Initial Setup

Complete your first setup through MoAI-ADK’s interactive setup wizard. The wizard asks only the five things a person has to choose — conversation language, name, the agent harness to deploy, the session permission mode, and whether to enable Jev typed judgments. Everything else (model policy, report format, quality gates, design workflow, and so on) is saved with its recommended default, and you can change it later.

Most settings are saved as YAML files under .moai/config/sections/, one concern per file, so changing a value means opening just that file. The session permission mode is the exception: it is written to your user-level Claude Code settings (see Page 2 below).

To initialize while creating a new project:

moai init my-project

This command creates the my-project folder and initializes MoAI-ADK.

To install MoAI-ADK into an existing project, move into that folder and run:

cd my-existing-project
moai init

Info

moai init installs directly into the current folder. For a new project, create it with moai init <project-name>.

The initialization wizard always runs the same flow — there is no mode flag that widens or narrows the question set; every user sees the same questions. It asks five questions spread over three pages. The progress indicator at the top of the screen (● ● ● ○ ○ 3 / 5) counts questions, not pages.

moai init my-project

Info

Git automation mode and provider are NOT asked by the wizard. moai init auto-detects them from the repository’s already-configured Git remotes. To change Git settings later, run moai update -c (--config) — only that path shows a separate set of Git questions (automation mode, provider, credentials).

Two basic values: conversation language and your name. The language comes pre-filled, and the name is pre-filled when your profile already has one; either way, pressing Enter moves you on.

Conversation language — the language MoAI uses when talking with you. The wizard switches to it immediately.

? Select conversation language
▸ English
  Korean (한국어)
  Japanese (日本語)
  Chinese (中文)

This setting is saved to .moai/config/sections/language.yaml.

Name — how MoAI addresses you. Leave it empty to skip.

? Enter your name: [name]

This setting is saved to the user.name field in .moai/config/sections/user.yaml.

Info

The project name is not asked. moai init uses the name you pass as moai init <project-name>, or the current folder name when you give none. You can also set it directly with the --name flag.

Choose which agent harness MoAI deploys and wires for this project. The choice decides which files land at the project root.

? Select the agent harness to deploy and wire
▸ Claude only (Recommended) - Deploy the .claude/ surface plus AGENTS.md (today's default behavior)
  GPT (Codex) only          - AGENTS.md and Codex surfaces only — no .claude/ tree, no CLAUDE.md, no .mcp.json
  Claude + Codex            - Same .claude/ deployment plus .codex/ wiring; .mcp.json provisioning forced on

The --llm claude|gpt|both flag takes precedence over this answer.

Choose the permission mode Claude Code sessions start in.

? Select the session permission mode
▸ Accept edits on (Recommended) - Auto-accept file edits; prompt for other tools
  Auto mode                     - Auto-approve tool calls under classifier safety checks
  Bypass permissions            - Skip all prompts; requires sandbox proof (Docker/gVisor/etc.)

This setting is written to your user-level Claude Code settings (defaultMode), not to a project YAML file. The default, Accept edits on, becomes defaultMode: acceptEdits. Bypass permissions applies only when a sandbox proof is present and the kill switch is off; otherwise it is applied as Auto mode instead. The --autonomy-tier semi-auto|automatic|fully-autonomous flag takes precedence over this answer.

Jev answers a typed question about supplied state and returns a probability; it makes no decision itself. A person reads its answer; where software uses it automatically, it is only as a signal — for example the order in which moai todo --auto considers queued cards, or an optional Kickoff cross-check that can only confirm or hand over to a person — never to approve, merge, or change a card on its own.

? Enable Jev typed judgments? (optional, off by default)

The default is off. Enabling it sends card text or request text to a third-party server, so decide with that in mind. This setting is saved to the workflow.jev.enabled field in .moai/config/sections/workflow.yaml.

Warning

This question is asked only by moai init. moai update -c does not ask it — to change it later, open the moai web settings.

The values below are saved with their defaults without asking. To change them, pass a flag, or use moai update -c or moai web after setup.

The per-agent model-assignment wizard question is retired. Since v3.2, subagents inherit the main session’s model and effort, so moai init does not ask for a model policy — there is nothing per-agent left to choose. What the profile keeps is the Session model policy: the default reasoning effort of the Claude session launched with this profile, applied when no effort level is chosen. Configure it with moai profile setup (the “Session model policy” question), not with the retired --model-policy / --profile flags — those are deprecated stubs that only print a warning. For the inheritance rule, see Model Policy; for how the per-agent matrix was retired, Profile Matrix.

Specify every value with flags to initialize without the wizard:

moai init my-project \
  --non-interactive \
  --llm claude \
  --autonomy-tier semi-auto \
  --enable-lsp=false \
  --enforce-quality

Once all steps are done, the config files are created:

graph TD
    A[".moai/"] --> B["config/"]
    A --> C["specs/"]
    A --> D["memory/"]
    B --> E["sections/"]
    E --> F["user.yaml"]
    E --> G["language.yaml"]
    E --> H["quality.yaml"]
    E --> I["llm.yaml"]
    E --> J["git-strategy.yaml"]

When installation deploys the skill mirror, it prefers a symbolic link. On systems where a link cannot be created, a copy is deployed instead, and the moai init completion summary then says so — the one thing worth knowing is that a copy does not follow the source the way a link does.

# User settings
vim .moai/config/sections/user.yaml

# Language settings
vim .moai/config/sections/language.yaml

# Session model policy (effort fallback)
moai profile setup

# Quality settings
vim .moai/config/sections/quality.yaml

Re-run the setup wizard to change the configuration:

# Re-run the setup wizard (recommended)
moai update -c

Info

The moai update -c command lets you keep existing settings while selectively reconfiguring only the items you want to change.

Check that the configuration is set up correctly:

moai doctor

This command validates whether Git is installed, the project structure (the .moai/ folder), the config files, and language-specific development tools. Check details with --verbose.

Once setup is complete, follow the Quick Start guide to create your first project.

moai --help