MoAI がプロジェクトの外に置く状態は、すべて ~/.moai の一箇所に集まります。プロファイルごとのデバッグログ、ダウンロードしたリリースバイナリ、セッションレジストリ、ワークツリー台帳、バックアップがここに溜まっていきます。長く使ったマシンでは、このディレクトリは静かに数ギガバイトまで育ちます — 誰も見ない場所なので、ディスクが埋まるまで気づかれません。

情報

一行でいうと: MOAI_HOME がホームルートの場所を決め、moai doctor がどれだけ埋まっているかを教え、moai clean --home が許可リストの内側だけを整理します。三つの表面でひとつの話です。

flowchart TD
    Root["~/.moai (ホームルート)"] --> Keep["保護 — 決して削除されない"]
    Root --> Clean["整理対象 — 許可リスト 4 カテゴリ"]

    Keep --> K1["config/ · state/ · projects/
worktrees/ · mcp/ · bin/
search/ · studio/ · plugins/"]
    Keep --> K2["launch.yaml · preferences.yaml
credentials で始まるすべてのファイル"]

    Clean --> C1["claude-profiles/<プロファイル>/debug/
(保持期間を過ぎたもの)"]
    Clean --> C2["releases/
(現行バージョン + 最新 3 個を除く)"]
    Clean --> C3["logs/
(ルートのログ、保持期間を過ぎたもの)"]
    Clean --> C4["backups/removed-*
(保持期間を過ぎたもの)"]

許可リストにないものはスキャナからそもそも見えません。そして保護は許可リストの内側でも勝ちます — 古い backups/removed-* ディレクトリの中に credentials で始まるファイルが一つでもあれば、そのディレクトリは丸ごとスキップされます。部分削除でバックアップを半端にするくらいなら、まったく手を触れません。

~/.claude はどの経路でも削除されません。moai doctor はサイズを報告するだけで、moai clean --home は読みもしません。

~/.moai の位置を別の場所に移すには、MOAI_HOME 環境変数にルートのパスを指定します。

export MOAI_HOME=/Volumes/work/moai-home

規則は三つです。

注意

シェルフックは MOAI_HOME に従いません。 この変数を読むのは Go バイナリ(moai CLI とそのサブコマンド)だけです。.claude/hooks/ 配下のシェルスクリプトラッパーや、~/.moai のパスを文字列として直接書く外部ツールはこの変数を参照しないため、既定の位置を見続けます。つまり MOAI_HOME を移すとGo 側の状態だけが付いてきて、シェルフックが使うパスとは分かれます。この制約を受け入れられるときだけ使ってください。

ユーザーのホーム自体は HOME 優先で解決されます。HOME が空でなければその値をそのまま使い、空のときだけ OS のホーム照会にフォールバックします。おかげでテストやコンテナで HOME を差し替えると、どのプラットフォームでも同じように効きます。

moai doctor の診断一覧に Home Disk Usage 項目が並びます。勧告 (advisory) の性格なので、超過しても他のコマンドを止めません。

moai doctor

この項目が報告するもの:

整理可能量が閾値(コンパイル既定値 500 MB)を超えると状態が WARN に変わり、メッセージが moai clean --home を勧めます。それ未満なら OK のままです。整理可能量の推定は moai clean --home が使うのと同じスキャナを呼ぶので、doctor が言う数字と clean が削除する一覧がずれることはありません。

# 既定は dry-run — 何が削除されるかを報告するだけ
$ moai clean --home

# 実際に削除
$ moai clean --home --force

• dry-run が既定です。--force を明示しないかぎり何も削除されません。
• 削除範囲は上の図の許可リスト 4 カテゴリだけです。
• releases/ では現在実行中のバージョンと残りのうち最新 3 個が保護され、それ以外のバイナリと対になる .sha256 ファイルが候補になります。version.json と LATEST は候補になりません。
• 残り三つのカテゴリ(debug/、ルートの logs/、backups/removed-*)は保持期間を過ぎたものだけが候補になります。

保持期間は HOME ティアの設定ファイル ~/.moai/config/sections/state.yaml から読まれます。

state:
  home_retention_days: 30

情報

このキーは、プロジェクトの .moai/config/sections/state.yaml にある state.retention_days(プロジェクトの実行成果物の保持)とは別のキーで別のティアです。ホームは一つなのにプロジェクトは複数あるため、プロジェクトごとに異なる保持期間で同じホームを整理してしまわないよう、読む場所を分けてあります。

flowchart TD
    A["moai doctor
Home Disk Usage を確認"] --> B{"整理可能量が
閾値を超えているか"}
    B -->|いいえ| Z["やることなし"]
    B -->|はい| C["moai clean --home
(dry-run — 一覧を読む)"]
    C --> D{"一覧は
納得できるか"}
    D -->|いいえ| E["state.home_retention_days を調整し
もう一度 dry-run"]
    E --> C
    D -->|はい| F["moai clean --home --force"]
    F --> G["moai doctor で再確認"]

• /moai clean — プロジェクトのデッドコード整理と --home 表面の違い
• moai doctor 診断 — 診断項目の全体とサブコマンド
• config セクションリファレンス — 設定ティアとセクションファイルの構造
• moai update — backups/removed-* を作る側