Installation

A guide to installing MoAI-ADK on your system. The installation is a single Go-built binary — no Python, no virtual environment, no package manager required.

MoAI-ADK v3.1.3 and later is distributed under the Apache-2.0 license.

Commercial use, modification, and distribution are free, with no obligation to open-source your code. For details, see Apache License 2.0.

Info

Note: MoAI-ADK 1.x (the Python version) was under the GPL-3.0 license. From v2.0.0 it was rewritten in Go and changed to Apache-2.0.

Check the following before installing:

MoAI-ADK is an extension framework that runs on top of Claude Code. Claude Code must be installed first.

claude --version

If you have not installed it yet, see the Claude Code official documentation.

MoAI-ADK uses a Git-based workflow. Git must be installed on your system.

git --version

Warning

Windows users: You must use Git Bash or WSL. Command Prompt (cmd.exe) is not supported.

If Git is not installed:

• Windows: Install Git for Windows from git-scm.com. Git Bash is installed alongside it.
• macOS: xcode-select --install or git-scm.com
• Linux: sudo apt install git (Ubuntu/Debian) or sudo dnf install git (Fedora)

Automatically installs the latest version with a single command.

macOS / Linux / WSL / Git Bash:

curl -fsSL https://adk.mo.ai.kr/install.sh | bash

Windows (PowerShell):

irm https://adk.mo.ai.kr/install.ps1 | iex

Info

The install script automatically detects the platform, downloads a pre-built binary from GitHub, verifies the SHA256 checksum, and configures the PATH. No Python or separate runtime is required.

Once the install completes, verify it:

moai version

# Install a specific version (specify the desired release tag)
curl -fsSL https://adk.mo.ai.kr/install.sh | bash -s -- --version <release-tag>

# Install to a custom directory
curl -fsSL https://adk.mo.ai.kr/install.sh | bash -s -- --install-dir /usr/local/bin

Info

Once MoAI-ADK is installed, you can switch to a different release tag in-process with moai update --version <tag> (stable, rc, or a previous version). See Update — Install a specific version.

If you have a Go development environment, you can build directly from source.

git clone https://github.com/modu-ai/moai-adk.git
cd moai-adk
make build

The built binary is created at ./bin/moai. Copy it to a location on your PATH:

cp ./bin/moai ~/.local/bin/

The install script determines the install directory in the following order:

Danger

MoAI-ADK 1.x (Python version) users must remove the old version first.

Since 1.x and 2.x use the same moai command, a leftover old version causes conflicts.

# If installed with uv
uv tool uninstall moai-adk

# If installed with pip
pip uninstall moai-adk

# If you want to back up your old settings
cp -r ~/.moai ~/.moai-v1-backup

curl -fsSL https://adk.mo.ai.kr/install.sh | bash

moai version

╭────────────────────────╮
│                        │
│    moai-adk v3.0.0     │
│                        │
│                        │
╰────────────────────────╯
 v3.0.0   none   built unknown

Info

The Go edition (v2.0+) is a single binary that needs no Python runtime or virtual environment. Startup time improved dramatically from about 800ms to 5ms.

For Windows users, here is how to install and use MoAI-ADK in the WSL (Windows Subsystem for Linux) environment.

If WSL is not installed, run the following in PowerShell (as administrator):

wsl --install

After installing and restarting Windows, Ubuntu is installed automatically.

In the WSL terminal, use the same command as Linux:

curl -fsSL https://adk.mo.ai.kr/install.sh | bash

In WSL you must distinguish Windows paths from WSL paths:

Info

Recommended: Creating projects on the WSL Linux filesystem (~/projects/) improves I/O performance 2-5x. Accessing the Windows filesystem (/mnt/c/) can degrade performance.

1. Use the Linux filesystem: create projects in the ~/projects/ directory
2. Set up Git credentials: configure Git credentials in WSL separately from Windows
3. Recommended terminal: use Windows Terminal to manage multiple WSL distributions

# Add to ~/.bashrc or ~/.zshrc
source ~/.cargo/env
export PATH="$HOME/.local/bin:$PATH"

# Grant execute permission
chmod +x ~/.claude/hooks/moai/*.sh

Move your project to the Linux filesystem:

# Move from Windows to WSL
cp -r /mnt/c/Users/name/project ~/projects/
cd ~/projects/project

A common problem MoAI-ADK 1.x (Python version) users can encounter.

pip and uv install packages to different locations. Mixing the two tools can make the moai command run an unexpected version.

• Running moai version shows a 1.x version
• A command not found: moai error occurs
• It runs from a path different from which moai

1. pip installs to the system Python path
2. uv tool installs to ~/.local/bin or ~/.cargo/bin
3. A different version runs depending on the PATH order

# 1. Remove all existing versions
uv tool uninstall moai-adk 2>/dev/null || true
pip uninstall moai-adk -y 2>/dev/null || true

# 2. Find and delete leftover binaries
which moai && rm $(which moai) 2>/dev/null || true
ls ~/.local/bin/moai && rm ~/.local/bin/moai 2>/dev/null || true

# 3. Install 2.x
curl -fsSL https://adk.mo.ai.kr/install.sh | bash

# 4. Verify
moai version

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

# Apply the configuration
source ~/.bashrc  # or source ~/.zshrc

1. MoAI-ADK 2.x is a Go binary unrelated to Python
2. Remove 1.x (Python version) before installing 2.x
3. Do not use pip and uv tool at the same time

command not found: moai

Solution:

1. Restart your terminal
2. Check your PATH configuration:

echo $PATH

3. Check where the binary is installed:

which moai || ls ~/.local/bin/moai

4. Add it to PATH manually:

# Bash/Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Permission denied

Solution:

chmod +x ~/.local/bin/moai

If an older moai command runs:

# Check which moai runs
which moai

# If 1.x remains, remove it
uv tool uninstall moai-adk
# or
pip uninstall moai-adk

# Restart the terminal, then verify 2.x
moai version

Once installation is complete, initialize a project:

moai init my-project

cd my-existing-project
moai init

To upgrade to the latest version:

moai update

# Check the version only (no update)
moai update --check

# Sync templates only (skip the binary update)
moai update --templates-only

# Config edit mode (re-run the setup wizard)
moai update -c

# Force update (user changes are backed up, then overwritten)
moai update --force

# Auto-approve mode (CI/CD)
moai update --yes

Info

Auto-preserved items: User settings, custom agents, custom commands, custom skills, custom hooks, SPEC documents, and reports are preserved automatically on update. Template files you modified are backed up and then 3-way merged.

For details, see the Update guide.

To fully remove MoAI-ADK, delete the binary and the settings directory:

# Delete the binary (delete the result of which moai)
rm "$(which moai)"

# Delete the settings directory (optional)
rm -rf "$HOME/.moai"

Learn how to configure MoAI-ADK in the Initial Setup wizard.