Personal dotfiles managed by chezmoi.

Note (Codex config): ~/.codex/config.toml は手動設定と Codex 所有の実行時状態が混在するため、ファイル全体をスナップショットせず modify_private_config.toml で管理対象キーだけを置換する。未管理の root key と table はそのまま保持されるので、Codex が project trust・通知先・Desktop 設定・plugin/MCP/hook 状態を更新しても chezmoi diff の対象にならない。~/.codex には認証情報・会話履歴・shell snapshot もあるため、ディレクトリ全体を chezmoi add ~/.codex しない。

Note (共通 CLI ツール管理ルール): .chezmoitemplates/cli-tool-management.md を正本とし、~/.codex/AGENTS.md と ~/.claude/rules/tool-management.md の両方へ同じ内容を展開する。ルール変更時は各出力テンプレートではなく共通テンプレートを編集する。

Note (agent skills): skill の導入チャネルは2種類ある。① GitHub lock チャネル: skills CLI で導入する skill の正本は ~/.agents/skills/ (store)。~/.claude/skills はそこへの symlink で、Claude Code から同じ skill を共有する。~/.agents/.skill-lock.json (どの GitHub ソースから入れたかの記録) を管理対象にしており、これが変わると run_onchange_after_install-skills.sh が chezmoi apply 時に各 skill を skills add で再取得する (Brewfile と同じ仕組み)。skill を追加/削除したら cp ~/.agents/.skill-lock.json dot_agents/dot_skill-lock.json で lock を source へ同期してコミットする。② 自作 skill チャネル: dot_agents/skills-local/<name>/ に SKILL.md（とサポートファイル）を置き、run_onchange_after_install-local-skills.sh が chezmoi apply 時に ~/.agents/skills/<name>/ へコピーする。GitHub チャネルは lock 外のフォルダを削除しないため両チャネルは共存できる。store 本体 (~/.agents/skills/**) は再生成可能なので .chezmoiignore で除外（自作スキルの source は dot_agents/skills-local/ に残る）。自作 skill を削除するときは source から消すだけでは足りず、run_onchange_after_install-local-skills.sh.tmpl の REMOVED_SKILLS 配列（store 側の実体を除去）と .chezmoiremove（~/.agents/skills-local/ 側の残骸を除去。残すと毎回再インストールされる）の2箇所に追記する。

Note (Claude Code plugins): プラグインの導入は run_onchange_after_install-claude-plugins.sh.tmpl の inline manifest（MARKETPLACES / PLUGINS 配列）が唯一の source of truth。chezmoi apply 時にこのスクリプトが claude plugin marketplace add + claude plugin install を冪等に流し、marketplace の clone と cache 本体を再生成する（skills store と同じ「ignore して run_onchange で再生成」方式）。Claude Code が実行時に所有する known_marketplaces.json / installed_plugins.json は .chezmoiignore 済みで追跡しない（タイムスタンプ等のドリフトが出ない）。有効化状態 enabledPlugins は modify_settings.json.tmpl が新規マシン用に seed し、以降は Claude Code の値を保持する。現在は公式 LSP (gopls-lsp / rust-analyzer-lsp @ claude-plugins-official) と ecc (ecc@ecc)、crit (crit@crit) を管理 (ecc は Claude Code CLI ≥ v2.1.0 必須)。プラグインを増減するときは manifest 配列を編集するだけ（JSON への手動反映や chezmoi re-add は不要）。

Note (Homebrew 管理の CLI): Brewfile.tmpl の「CLI・シェル環境（Homebrew 管理）」に formula と CLI の cask をまとめ、各定義行の右側に Homebrew 管理理由を記載する。既存方針・設定・配布情報から理由を確認し、特定できないものは「個別の管理理由は未確認」と明記する。diff-pdf は aqua 標準レジストリに未登録で、公式配布に macOS 用バイナリがないため、Homebrew formula で Poppler・Cairo・wxWidgets 等の依存ライブラリとともに管理する。通常の chezmoi apply で brew bundle が実行され、ほかの Brewfile エントリとともにインストール・更新される。

Note (op / 1Password CLI): op は「single-binary CLI は原則 aqua (mise)」方針の例外で、Brewfile.tmpl の cask "1password-cli" で管理する。aqua registry の 1password/cli は配布元が GitHub release ではなく cache.agilebits.com のため type: http 扱いで repo_owner/repo_name を持たず、mise ではバージョン一覧を引けない (ls-remote / latest / "latest" 指定が不可 → 更新検知が効かず手動追従になる)。上流が digest を公開していないので lockfile にも checksum が載らない。aqua を選ぶ利点が両方とも成立しない一方、資格情報ツールは追従が遅れるほうが痛いため brew に置いている (cask は op の zsh 補完も同梱する)。バージョン追従は brew upgrade に任せる。

Note (二重チャネル管理ツール): crit / herdr は CLI（mise）と Claude 連携（plugin / skill / hook）の複数チャネルで同じツールを管理している。CLI のバージョンだけ上げると連携側が古いままズレるため、更新時は両方を揃えること。対応表と更新手順は CLAUDE.md の「二重チャネル管理ツール（CLI + Claude 連携）」を参照。

以下はリポジトリ専用のメタファイル、認証トークン・機密情報、アプリが所有する実行時状態のため管理対象外。

.tmpl ファイルは chezmoi が Go template として評価する。変数は2種類:

• 手動設定が必要 — ~/.config/chezmoi/chezmoi.toml の [data] に記述する。~/.config/chezmoi/ は機密のためこのリポジトリには含まれないので、新規マシンでは chezmoi apply の前に必ず設定する (下記 step 4)。
• chezmoi 自動提供 — 設定不要。

新たにテンプレートを追加する場合、ファイル名に .tmpl を付ければ上記の変数を参照できる。手動変数を増やしたときはこの表と step 4 を更新すること。

# 1. Install Homebrew (https://brew.sh)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Install chezmoi and ghq
brew install chezmoi ghq

# 3. Clone dotfiles via ghq
ghq get [email protected]:Msksgm/dotfiles.git    # → ~/workspace/github.com/Msksgm/dotfiles

# 4. Configure chezmoi (sourceDir + テンプレート手動変数。詳細は "Template variables" 参照)
mkdir -p ~/.config/chezmoi
cat > ~/.config/chezmoi/chezmoi.toml <<'EOF'
sourceDir = "~/workspace/github.com/Msksgm/dotfiles"

[data]
  github_username = "Msksgm"               # → ~/.gitconfig の user.name
  github_email    = "[email protected]"      # → ~/.gitconfig の user.email
  # 以下4変数は private GitHub repo のツールを mise で入れるマシンでだけ設定（任意）。
  # 詳細は下記 "Private tool" 参照。4つはセットで必要。
  private_tool_repo       = "<owner>/<repo>"
  private_tool_version    = "<version>"    # 例: "1.2.3"
  op_account              = "<1Password アカウント識別子>"
  private_tool_token_ref  = "op://<Vault>/<Item>/<field>"
  # container runtime cask はマシンごとに入れ分ける（任意・どちらか一方 or 両方）。
  # 設定したキーの cask だけが `brew bundle` で install される。
  # install_orbstack       = true
  # install_docker_desktop = true
EOF

# 5. Apply dotfiles
#    run_onchange_install-packages.sh runs `brew bundle` automatically,
#    so Brewfile packages (powerlevel10k 等) もここでインストールされる
#    mise.lock も chezmoi 管理下なので、mise のツールは全マシンで同一 version/checksum で入る
chezmoi apply

private GitHub repo のリリースを mise の github バックエンドで導入する仕組み。mise install が private repo を認証するために GITHUB_TOKEN が要るので、run_onchange_after_install-mise-tools.sh が 1Password から op-vault 経由でトークンを取得して mise install の直前に export する。public repo にシークレット・内部参照（対象 repo 名・バージョンも含む）を残さないため、op アカウント・シークレット参照・repo 名・バージョンはすべて chezmoi の [data] (上記 step 4) から注入する。

opt-in: private_tool_repo を設定したマシンでだけ有効（hasKey ゲート）。未設定のマシンでは config.local.toml 自体が展開されず (.chezmoiignore で制御)・トークン処理も走らないため、chezmoi apply は通常どおり成功する。private_tool_repo を設定していて private_tool_version を設定し忘れた場合は、chezmoi がキー未定義エラーで apply を止める（設定漏れに気付けるようにあえて fail-fast にしている）。

なぜ config.toml と別ファイルなのか: mise の lockfile は「宣言した config ファイル名の .toml → .lock」で決まり、~/.config/mise/config.toml の lock は ~/.config/mise/mise.lock。この mise.lock は再現性のため dotfiles で追跡している (dot_config/mise/private_mise.lock) ので、private tool をここに書くと repo 名とリリースアセット URL が public repo に載ってしまう。そのため private tool は ~/.config/mise/config.local.toml に隔離し、lock を mise.local.lock（追跡対象外）へ分離している。

• conf.d/*.toml は lockfile が親ディレクトリの mise.lock に合流するため隔離手段にならない。
• MISE_ENV 方式は全プロジェクトディレクトリに波及するうえ、chezmoi のスクリプトは非対話 bash で走り .zshenv を読まないため apply 時にツールが入らない。

バージョン更新: ~/.config/chezmoi/chezmoi.toml の private_tool_version を書き換えて chezmoi apply するだけ。dotfiles 側のコミットは不要（スクリプトのバージョン hash 行が変わるので mise install も再実行される）。mise.local.lock の更新もあわせて行うなら mise lock -g（追跡対象外なのでコミットは不要）。

導入するマシンで一度だけ用意しておくもの:

1. 1Password デスクトップアプリの CLI 連携を有効化し、op-vault init を実行する (op-vault は 1Password SDK 利用のため op CLI に依存しない。op 自体は Brewfile で別途入るが、この仕組みの前提ではない)。
2. private repo を読める GitHub PAT を 1Password に保存し、その op://<Vault>/<Item>/<field> 参照を private_tool_token_ref に設定する。
3. private_tool_repo / op_account / private_tool_token_ref を ~/.config/chezmoi/chezmoi.toml の [data] に設定する（3つセット）。

トークンを解決できない (1Password ロック・変数未設定等) 場合、スクリプトは 中断する (silent skip しない)。導入対象マシンで一時的に他ツールだけ入れたいときは 1Password を解錠してから再 apply すること。

~/.config/mise/mise.lock（全ツールの version / URL / checksum を複数プラットフォーム分固定した lockfile）は dot_config/mise/private_mise.lock として追跡している。生成物なので手で編集せず、ツールを追加・バージョン変更したら mise lock -g → cp で source へ同期してコミットする（dot_agents/dot_skill-lock.json と同じ「実体を cp で追跡」パターン）。mise install だけでは現在の platform 分しか lock されず、削除済みツールのエントリも残るため mise lock -g を挟むのが必須。

手順・検証コマンド・注意点は .agents/skills/mise-lock-update/SKILL.md に集約している（Codex では $mise-lock-update、Claude Code では /mise-lock-update で起動できる。.claude/skills は .agents/skills への symlink）。

cp した直後の chezmoi diff は空にならない。 install-mise-tools.sh が new file mode 100755 として全文表示される。これはファイル差分ではなく「apply したらこのスクリプトが走る」という予告で、lockfile の中身が変わるとスクリプトに埋め込まれた # lockfile hash: 行が変わり run_onchange の再実行対象になるため。もう一度 chezmoi apply すれば mise install が冪等に走って diff が収束する。 見るべきは「diff が空か」ではなく「.config/mise/mise.lock のファイル差分が出ていないか」。

# Preview what would change
chezmoi diff

# Apply all managed files
chezmoi apply

# List managed files
chezmoi managed

# Re-apply after editing source
chezmoi apply -v

# Pull remote changes and apply
chezmoi update

# Claude Code の blocklist / config を source 側に同期 (drift したとき)
# settings.json は modify_ が、plugins の marketplaces/installed は run_onchange が
# 面倒を見るので re-add 不要。手動編集したときだけ blocklist/config を取り込む。
chezmoi re-add ~/.claude/plugins/blocklist.json ~/.claude/plugins/config.json

# brew drift: インストール済みだが Brewfile にない formula を追加
brewfile-add <formula>
brewfile-add --cask <cask>

# drift チェックを手動で強制実行（1日1回キャッシュを無視）
# ※ source して関数として呼ぶ必要がある（スクリプト直接実行では --force が届かない）
source ~/.zsh/brew_drift_check.zsh && brew-drift       # Brewfile との差分を確認
source ~/.zsh/drift_check.zsh && dotfiles-drift        # git・chezmoi の差分を確認

Note (Claude Code 設定の drift): settings.json の feedbackSurveyState / enabledPlugins / extraKnownMarketplaces（Claude Code が実行時に書き換えるキー）は modify_settings.json.tmpl が実ファイルの値を保持するため diff は出ない。plugins/known_marketplaces.json / installed_plugins.json は .chezmoiignore 済みで追跡しない。→ 以前のようにタイムスタンプや git SHA で chezmoi diff が出続けることはない。