インストール

MoAI-ADK をシステムにインストールする方法を案内します。インストールされるのは Go でビルドされた単一バイナリ 1 つだけです。Python も仮想環境もパッケージマネージャーも必要ありません。

MoAI-ADK v3.1.3 以上は Apache-2.0 ライセンス の下で配布されます。

商用利用、修正、配布が自由で、ソースコード公開の義務がありません。詳しい内容は Apache License 2.0 を参照してください。

情報

参考: MoAI-ADK 1.x (Python 版) は GPL-3.0 ライセンスでした。v2.0.0 から Go 言語で書き直され Apache-2.0 に変更されました。

インストール前に次の項目を確認してください:

MoAI-ADK は Claude Code の上で動作する拡張フレームワークです。まず Claude Code がインストールされている必要があります。

claude --version

まだインストールしていない場合は Claude Code 公式ドキュメント を参照してください。

MoAI-ADK は Git ベースのワークフローを使います。システムに Git がインストールされている必要があります。

git --version

注意

Windows ユーザー: 必ず Git Bash または WSL 環境で使ってください。Command Prompt (cmd.exe) は対応していません。

Git がインストールされていない場合:

• Windows: git-scm.com から Git for Windows をインストールしてください。Git Bash が一緒にインストールされます。
• macOS: xcode-select --install または git-scm.com
• Linux: sudo apt install git (Ubuntu/Debian) または sudo dnf install git (Fedora)

1 つのコマンドで最新バージョンを自動インストールします。

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

情報

インストールスクリプトは自動的にプラットフォームを検出し、GitHub から事前ビルドされたバイナリをダウンロードし、SHA256 チェックサムを検証し、PATH を設定します。Python や別途のランタイムは必要ありません。

インストールが完了したら確認してください:

moai version

# 特定バージョンのインストール (希望するリリースタグを指定)
curl -fsSL https://adk.mo.ai.kr/install.sh | bash -s -- --version <リリースタグ>

# カスタムディレクトリにインストール
curl -fsSL https://adk.mo.ai.kr/install.sh | bash -s -- --install-dir /usr/local/bin

情報

MoAI-ADK インストール後は moai update --version <tag> で別のリリースタグ(stable、rc、旧バージョン)にインプロセスで切替できます。詳しくは Update — 特定バージョンのインストール を参照してください。

Go 開発環境がある場合はソースから直接ビルドできます。

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

ビルドされたバイナリは ./bin/moai に生成されます。PATH が指定された場所にコピーしてください:

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

インストールスクリプトは次の順序でインストールディレクトリを決定します:

警告

MoAI-ADK 1.x (Python 版) ユーザーは必ず先に既存バージョンを削除してください。

1.x と 2.x は同じ moai コマンドを使うので、既存バージョンが残っていると衝突が発生します。

# uv でインストールした場合
uv tool uninstall moai-adk

# pip でインストールした場合
pip uninstall moai-adk

# 既存の設定をバックアップしたいなら
cp -r ~/.moai ~/.moai-v1-backup

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

moai version
# 出力例: moai <バージョン> (commit: <ハッシュ>, built: <ビルド日付>)

情報

Go エディション (v2.0+) は単一バイナリで、Python ランタイムや仮想環境が必要ありません。起動時間は約 800ms から 5ms へと大きく短縮されました。

Windows ユーザー向けに WSL (Windows Subsystem for Linux) 環境でのインストールおよび使用方法を案内します。

WSL がインストールされていない場合、PowerShell (管理者権限) で次のコマンドを実行してください:

wsl --install

インストール後に Windows を再起動すると Ubuntu が自動的にインストールされます。

WSL ターミナルで Linux と同じコマンドを使います:

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

WSL では Windows パスと WSL パスを区別する必要があります:

情報

推奨: WSL の Linux ファイルシステム (~/projects/) にプロジェクトを作成すると I/O 性能が 2-5 倍向上します。Windows ファイルシステム (/mnt/c/) にアクセスすると性能が低下することがあります。

1. Linux ファイルシステムの使用: プロジェクトは ~/projects/ ディレクトリに作成
2. Git 資格情報の設定: Windows とは別に WSL で Git 資格情報を構成
3. 推奨ターミナル: Windows Terminal を使って複数の WSL ディストリビューションを管理

# ~/.bashrc または ~/.zshrc に追加
source ~/.cargo/env
export PATH="$HOME/.local/bin:$PATH"

# 実行権限を付与
chmod +x ~/.claude/hooks/moai/*.sh

Linux ファイルシステムにプロジェクトを移動してください:

# Windows から WSL へ移動
cp -r /mnt/c/Users/name/project ~/projects/
cd ~/projects/project

MoAI-ADK 1.x (Python 版) ユーザーが遭遇しうる一般的な問題です。

pip と uv は互いに異なる場所にパッケージをインストールします。2 つのツールを混用すると moai コマンドが予想外のバージョンを実行することがあります。

• moai version を実行したときに 1.x バージョンが表示される
• command not found: moai エラーが発生
• which moai と異なる場所から実行される

1. pip はシステム Python のパスにインストール
2. uv tool は ~/.local/bin または ~/.cargo/bin にインストール
3. PATH の順序に応じて異なるバージョンが実行される

# 1. すべての既存バージョンを削除
uv tool uninstall moai-adk 2>/dev/null || true
pip uninstall moai-adk -y 2>/dev/null || true

# 2. 残ったバイナリの確認と削除
which moai && rm $(which moai) 2>/dev/null || true
ls ~/.local/bin/moai && rm ~/.local/bin/moai 2>/dev/null || true

# 3. 2.x のインストール
curl -fsSL https://adk.mo.ai.kr/install.sh | bash

# 4. 確認
moai version

# ~/.bashrc または ~/.zshrc に追加
export PATH="$HOME/.local/bin:$PATH"

# 設定の適用
source ~/.bashrc  # または source ~/.zshrc

1. MoAI-ADK 2.x は Python と無関係な Go バイナリです
2. 1.x (Python 版) を削除してから 2.x をインストールしてください
3. pip と uv tool を同時に使わないでください

command not found: moai

解決方法:

1. ターミナルを再起動してください
2. PATH 設定を確認してください:

echo $PATH

3. バイナリがインストールされた場所を確認してください:

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

4. PATH に手動で追加してください:

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

Permission denied

解決方法:

chmod +x ~/.local/bin/moai

以前のバージョンの moai コマンドが実行される場合:

# どの moai が実行されるか確認
which moai

# 1.x が残っているなら削除
uv tool uninstall moai-adk
# または
pip uninstall moai-adk

# ターミナル再起動後に 2.x を確認
moai version

インストールが完了したらプロジェクトを初期化してください:

moai init my-project

cd my-existing-project
moai init

最新バージョンにアップグレードするには:

moai update

# バージョン確認のみ (アップデートしない)
moai update --check

# テンプレート同期のみ (バイナリアップデートをスキップ)
moai update --templates-only

# 設定編集モード (初期化ウィザードの再実行)
moai update -c

# 強制アップデート (ユーザー変更事項はバックアップ後に上書き)
moai update --force

# 自動承認モード (CI/CD)
moai update --yes

情報

自動保存される項目: ユーザー設定、カスタムエージェント、カスタムコマンド、カスタムスキル、カスタムフック、SPEC ドキュメント、報告書はアップデート時に自動的に保存されます。ユーザーが修正したテンプレートファイルはバックアップ後 3-way マージされます。

詳しい内容は アップデートガイド を参照してください。

MoAI-ADK を完全に削除するにはバイナリと設定ディレクトリを削除してください:

# バイナリ削除 (which moai の結果で削除)
rm "$(which moai)"

# 設定ディレクトリ削除 (オプション)
rm -rf "$HOME/.moai"

初期設定ウィザード で MoAI-ADK の構成方法を確認しましょう。