Initial Setup

Complete your first setup through MoAI-ADK’s interactive setup wizard. It configures the language, model policy, report format, and quality/workflow settings to match your development environment. Every value you set here is saved as a YAML file under .moai/config/sections/, so you can change it any time later by editing the file directly or re-running the wizard.

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 fixed 3-page flow — there is no mode flag that widens or narrows the question set; every user sees the same questions.

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

Choose the language Claude will respond in. Every subsequent question renders in this language.

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

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

The user name used in the config files. Press Enter to skip.

? Enter your name: [name]

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

The name of your project. The default is the current directory name.

? Enter project name: [my-project]

Choose the AI model tier assigned to agents — the core Tokenomics setting.

? Choose the performance tier:
▸ Medium - Opus 5 (high~low) + Sonnet (low, single-shot rows only)
  High - Opus 5 (max~medium) + Sonnet (low, single-shot rows only)
  Low - Opus 5 (medium~low) + Sonnet (low, docs/e2e/single-shot rows)

This setting is saved in the performance_tier field of .moai/config/sections/llm.yaml and is read as a legacy alias of the profile field (the profile matrix column). Specifying the --profile high|medium|low flag directly stores it in the profile field (the legacy value max is accepted as input and normalized to high). For the per-profile agent model+effort mapping, see the Profile Matrix page.

Choose whether reports are generated as HTML+Markdown or Markdown only.

? Choose the report format:
▸ HTML + Markdown (Recommended) - generate both a browser-viewable HTML report and Markdown
  Markdown only - generate Markdown reports only (lighter, diff-friendly)

This setting is saved in the report.format field of .moai/config/sections/report.yaml.

Choose whether to enable language-server diagnostics in the run phase. The default is enabled (Yes); answer No to opt out.

This setting is saved in the lsp.enabled field of .moai/config/sections/lsp.yaml.

Choose whether to enforce the TRUST 5 quality gates.

• Enforce quality gates (default: Yes) — block implementation from proceeding when a quality gate fails

This setting is saved in the constitution.enforce_quality field of .moai/config/sections/quality.yaml.

Choose the project collaboration mode.

? Select project mode:
▸ Personal (Recommended) - Solo developer
  Team - Multi-developer setup

This setting is saved in the project.mode field of .moai/config/sections/project.yaml.

Choose whether to enable the MoAI design pipeline and Claude Design integration.

• Enable design workflow (default: Yes)
• Enable Claude Design integration (default: Yes, shown only when design is enabled)

These settings are saved in the design.enabled / design.claude_design.enabled fields of .moai/config/sections/design.yaml.

By specifying all values with flags, you can initialize without the wizard:

moai init my-project \
  --non-interactive \
  --project-mode personal \
  --profile medium \
  --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

# Model policy (performance tier)
vim .moai/config/sections/llm.yaml

# 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