CLI 利用方法

agent-dotfiles と review-orchestrator のインストール、基本コマンド、--target / --repo の指定方法をまとめる。

新規環境の順序

新しいマシンでは、まず dotfiles の scripts/bootstrap.sh を入口にして secret substrate と PATH を整える。dotfiles 側の bootstrap は AGENT_REPO を使って agent-dotfiles repository の clone / fast-forward pull、CLI install、agent-dotfiles status --repo "$AGENT_REPO" まで実行する。

# 1) dotfiles 側で bootstrap を実行する
git clone https://github.com/TomoakiMizuno/dotfiles.git /path/to/dotfiles
cd /path/to/dotfiles
export AGENT_REPO="${AGENT_REPO:-$HOME/ghq/github.com/TomoakiMizuno/agent-dotfiles}"
bash scripts/bootstrap.sh --dry-run
bash scripts/bootstrap.sh

# 2) status の差分を確認してから必要に応じて取り込む
agent-dotfiles status --repo "$AGENT_REPO"
agent-dotfiles import --repo "$AGENT_REPO"

agent-dotfiles import は AI Agent runtime 設定を home directory へ反映するため、dotfiles 側の bootstrap では自動実行しない。bootstrap / 新規環境では --repo を明示する。自動検出は普段の作業では便利だが、初期セットアップでは別 clone や ghq 未設定の影響を避けるため、対象リポジトリを固定した方がよい。

インストール

このリポジトリには 3 本の CLI が含まれる:

バイナリ	役割
`agent-dotfiles`	`~/.claude/` `~/.codex/` `~/.copilot/` `~/.gemini/` `~/.agents/skills/` をリポジトリと同期する CLI
`review-orchestrator`	`multi-review` / `adversarial-review` の Go orchestration と、`babysit-reviews` の Copilot 完了判定に使う CLI
`agchat`	installed agmsg scripts を worktree 単位の default team で呼ぶ会話用 CLI

推奨: `make install` で 3 本まとめて入れる

git clone https://github.com/TomoakiMizuno/agent-dotfiles.git
cd agent-dotfiles
make install

これは go install ./cmd/agent-dotfiles、go install ./cmd/review-orchestrator、go install ./cmd/agchat を順に実行し、各バイナリを $(go env GOBIN)（未設定なら $(go env GOPATH)/bin）に配置する。PATH にそのディレクトリが含まれていることを確認すること。

設定ファイル / skill の同期まで一気に済ませたい場合は make bootstrap。make install のあとに agent-dotfiles import を確認付きで実行する。差分を先に確認したい場合は make bootstrap ではなく、make install、agent-dotfiles status --repo <repo>、agent-dotfiles import --repo <repo> の順に分けて実行する。

make bootstrap

新規環境では、shell loader や secret substrate も含めて整えるため、先に dotfiles 側の scripts/bootstrap.sh を使う。

agent-dotfiles import は ~/.claude/ ~/.codex/ ~/.copilot/ ~/.gemini/ ~/.agents/skills/ を上書きする。import 実行前には、可能なら agent-dotfiles status --repo /path/to/agent-dotfiles で差分を見てから取り込む。未エクスポートの変更があれば事前に agent-dotfiles export --repo /path/to/agent-dotfiles を実行しておくこと。

リポジトリを clone せずに入れる

go install github.com/TomoakiMizuno/agent-dotfiles/cmd/agent-dotfiles@latest
go install github.com/TomoakiMizuno/agent-dotfiles/cmd/review-orchestrator@latest
go install github.com/TomoakiMizuno/agent-dotfiles/cmd/agchat@latest

agent-dotfiles だけが必要であれば 1 行目のみで足りる。review-orchestrator は multi-review / adversarial-review の実行本体であり、babysit-reviews skill からも呼ばれる。

個別 install / 開発用 build

コマンド	内容
`make install-agent-dotfiles`	`agent-dotfiles` だけを `go install`
`make install-review-orchestrator`	`review-orchestrator` だけを `go install`
`make install-agchat`	`agchat` だけを `go install`
`make build`	`agent-dotfiles` をカレントディレクトリに `go build`（`./agent-dotfiles`、PATH に入らない）
`make reset-codex-sessions`	Superset / Codex.app 経由の Codex セッションを強制終了し、`codex logout` する
`make setup-codex-workspace-sync`	`~/.codex/hooks` を同期し、Codex worktree の launchd 自動同期と `git worktreeinclude apply` を有効化
`make help`	利用できるターゲット一覧を表示

Windows でも go install ./cmd/review-orchestrator で review-orchestrator.exe を生成でき、review-orchestrator.exe --help を実行できる。Windows では Unix と同じ process group kill は行わず、multi-review 実行時の完全な子プロセス制御互換性は後続対応とする。multi-review 実行時に必要な gh / agent CLI / wrapper / validation command の条件別一覧は review 運用の prerequisites を参照する。

基本コマンド

# 設定をリポジトリにエクスポート
agent-dotfiles export

# リポジトリから設定をインポート
agent-dotfiles import

# 同期状態を確認
agent-dotfiles status

# リポジトリを更新してから同期状態を確認
agent-dotfiles update
agent-dotfiles update --target codex/config.toml

# 明示した場合だけpull後にimportまで実行
agent-dotfiles update --import --target codex/config.toml

# repo / command / 管理対象の前提を診断
agent-dotfiles doctor
agent-dotfiles doctor --repo /path/to/agent-dotfiles --no-network

# import/export 前の差分を unified diff で確認
agent-dotfiles diff
agent-dotfiles diff --target codex/config.toml

# リポジトリ側の source path を確認
agent-dotfiles source-path
agent-dotfiles source-path codex/config.toml

# リポジトリ側の directory で subshell を起動
agent-dotfiles cd
agent-dotfiles cd codex/config.toml

# 解決済み repo root で git を実行
agent-dotfiles git -- status --short
agent-dotfiles git -- diff

agchat

agchat は ~/.agents/skills/agmsg/scripts/ に install 済みの agmsg script を短く呼ぶ wrapper。agmsg の DB や teams/ を直接読まず、whoami.sh / identities.sh / join.sh / send.sh / inbox.sh / team.sh / history.sh / request-claude.sh だけを実行する。

team 未指定時は git rev-parse --show-toplevel で worktree root を解決し、repo 名と root path hash から agchat-<repo>-<hash> 形式の deterministic default team を作る。同じ worktree なら別プロセス・別 agent でも同じ team になり、別 worktree では hash が変わる。明示 team を使いたい場合は --team <name> を指定する。--team は team 名だけを上書きし、agmsg の project path は git root または --repo <path> から解決する。

self identity は --type / --name の明示値、runtime 環境、whoami.sh の順で解決する。runtime 環境から agent type だけ推定できても、name が env または whoami.sh で解決できない場合は --name を要求して fail fast する。解決できた場合は対象 team に join.sh で自動参加してから操作する。

# default は inbox 確認
agchat

# 同じ worktree の default team へ送信
agchat send claude "確認してください"

# one-shot Claude Code 依頼。request-claude.sh だけを呼び、worker 系 script は使わない
agchat ask claude prompt.md

# team / history の確認
agchat team
agchat history

# default team ではなく明示 team を使う
agchat --team issue-584 send claude "確認してください"

# runtime / whoami.sh から self identity を推定できない shell では明示する
agchat --type codex --name codex inbox

shell alias や bootstrap 確認は dotfiles 側の責務であり、この repository では agchat binary と install target だけを提供する。

doctor

doctor は新規環境や dotfiles bootstrap 後に、agent-dotfiles を使うための前提をまとめて確認する。repo 解決、git repository 判定、origin が agent-dotfiles を指していること、必須 command の git / go、optional command の review-orchestrator、review toolchain の条件付き command、管理 root と主要ファイルの存在を human-readable に出力する。

agent-dotfiles doctor
agent-dotfiles doctor --repo /path/to/agent-dotfiles
agent-dotfiles doctor --repo "$AGENT_REPO" --no-network

missing git / go、repo origin の不一致、管理 root や主要ファイルの欠落は error として終了コード 1 になる。review-orchestrator、gh、codex、claude、copilot、bash、make、JS package managers、jq は review 用の条件付き command なので、PATH に無い場合は warning に留める。gh の認証状態は gh auth status --hostname github.com で確認する。既定で network 依存チェックは行わないため、--no-network は bootstrap script などで意図を明示したい場合に指定する。条件別の意味は review 運用の prerequisites を参照する。

Issue 作成、Issue なし実装、Issue 実装、multi-review、E2E、PR 作成、PR 本文更新の使い分けは Issue workflow skill guide を参照する。

source-path / cd / git

source-path は解決済み repo root、または repo display path に対応するリポジトリ側の絶対パスを出力する。target 未指定時は repo root を出力し、target 指定時は export / import / status --target と同じ repo display path モデルで検証する。

agent-dotfiles source-path
agent-dotfiles source-path codex/config.toml
agent-dotfiles source-path claude/skills/multi-review
cd "$(agent-dotfiles source-path)"

source-path <file> は file path をそのまま出力する。一方、agent-dotfiles cd <file> はその親 directory で subshell を起動する。cd コマンドは親 shell の cwd を変更できないため、親 shell の cwd を変えたい場合は cd "$(agent-dotfiles source-path)" を使う。

agent-dotfiles cd
agent-dotfiles cd claude/skills/multi-review
agent-dotfiles cd codex/config.toml

agent-dotfiles cd は $SHELL を優先し、未設定時は OS 標準 shell に fallback する。子 shell には AGENT_DOTFILES_REPO=<resolved repo absolute path> を追加する。

git は解決済み repo root を cwd とする git wrapper。内部では git -C <resolved repo> <args...> を実行し、stdout / stderr / stdin は git subprocess へそのまま接続する。status --short や diff --stat のような git 側 flag を agent-dotfiles 側に誤解釈させないため、通常は -- の後ろに git 引数を書く。

agent-dotfiles git -- status --short
agent-dotfiles git -- diff
agent-dotfiles git -- pull --ff-only
agent-dotfiles git --repo /path/to/agent-dotfiles -- status --short

update

update は解決済み repo root で git pull --ff-only を実行し、その後に status 相当の同期状態を表示する。chezmoi の update と違い、デフォルトでは home directory への反映は行わない。

agent-dotfiles update
agent-dotfiles update --repo /path/to/agent-dotfiles
agent-dotfiles update --target codex/config.toml --target claude/skills/multi-review

pull 後に設定を反映したい場合だけ --import を付ける。--target は既存の status / import と同じ repo display path モデルで検証され、--import なしでは status の絞り込み、--import ありでは import 対象の絞り込みに使われる。

agent-dotfiles update --import --target codex/config.toml
agent-dotfiles update --import --target claude/agents/github-issue-validator.md

pull 前に repository が dirty の場合、update はデフォルトで中止する。未コミット差分を把握したうえで続行する場合だけ --allow-dirty を明示する。

agent-dotfiles update --allow-dirty

target 指定

export / import / status / update / diff は repo 側の表示パスを基準に --target で対象を絞り込める。未指定時は従来通り全体を同期・表示する。複数指定する場合は --target を繰り返す。

agent-dotfiles export --target codex
agent-dotfiles export --target codex/config.toml --target gemini/settings.json
agent-dotfiles export --target codex/rules --target codex/hooks --target claude/skills/multi-review
agent-dotfiles export --target codex/memories
agent-dotfiles import --target copilot/config.json
agent-dotfiles import --target codex/hooks
agent-dotfiles import --target codex/memories
agent-dotfiles import --target claude/skills/multi-review
agent-dotfiles import --target claude/agents/github-issue-validator.md
agent-dotfiles status --target codex
agent-dotfiles status --target codex/memories
agent-dotfiles diff --target codex/config.toml
agent-dotfiles source-path codex/memories
agent-dotfiles status --target claude/agents/github-issue-validator.md --target claude/skills/multi-review --target gemini/settings.json

指定できる target は管理対象内の repo display path。service target は claude / codex / copilot / gemini。file target は claude/agents/github-issue-validator.md、codex/config.toml、gemini/settings.json、copilot/config.json など。directory target は claude/agents、codex/rules、codex/memories、claude/skills/<skill> などを指定できる。

codex/memories は Codex が生成する memory state の PC 移行・明示 backup 用 target。普段の設定同期ノイズを避けるため、target 未指定や --target codex では ~/.codex/memories/ を同期・表示しない。必要な時だけ export --target codex/memories で repo 側へ保存し、移行先で import --target codex/memories を実行する。通常テキストだけを同期し、.git、sessions/、sqlite/db、binary は対象外。構造化 secret sanitizer は適用されないため、private repository へ commit する前に生成内容を確認する。

Codex runtime の DB や session state は export / import / status / diff の管理対象ではない。~/.codex/state_5.sqlite、~/.codex/logs_2.sqlite、~/.codex/sessions/、~/.codex/archived_sessions/、~/.codex/process_manager/ は実行時データとして保持し、整合確認が必要な場合は codex-state-doctor report --format json の read-only report で missing session、orphan session、archived state mismatch、巨大 session、古い process_manager entry を確認する。report は候補操作とリスクを出すだけで、自動 repair は行わない。

Codex App worktree を Superset workspace へ自動同期し、作成後に .worktreeinclude 相当のローカル設定を適用する launchd watcher は、次の順で有効化する。git-worktreeinclude は外部依存であり、apply 本体は agent-dotfiles では再実装しない。

brew install satococoa/tap/git-worktreeinclude
make setup-codex-workspace-sync

この target は先に agent-dotfiles import --repo "$(pwd)" --target codex/hooks を実行して ~/.codex/hooks/ を repo 管理版へ揃え、その後 ~/Library/LaunchAgents/com.agent-dotfiles.codex-workspace-sync.plist を生成・登録する。plist の WatchPaths には CODEX_WORKTREE_SYNC_WATCH_PATH と WORKTREEINCLUDE_APPLY_ROOTS の各 root を入れる。wrapper は同じ lock の内側で swt codex sync-workspaces --all --quiet を実行し、成功後に scan root 配下の worktree ごとに git -C "$worktree_path" worktreeinclude apply --from auto --quiet を実行する。既存ファイルを上書きしたい場合だけ WORKTREEINCLUDE_APPLY_FORCE=1 を付けて setup し直す。

apply 対象 root は WORKTREEINCLUDE_APPLY_ROOTS で PATH 風の : 区切りとして指定できる。未指定時は CODEX_WORKTREE_SYNC_WATCH_PATH（未指定なら ~/.codex/worktrees）と ~/.superset/worktrees を対象にする。別 root を明示する例:

WORKTREEINCLUDE_APPLY_ROOTS="$HOME/.codex/worktrees:$HOME/.superset/worktrees" make setup-codex-workspace-sync

git-worktreeinclude が PATH にない場合、setup は brew install satococoa/tap/git-worktreeinclude を案内する。watcher 実行時は警告ログを残して sync 自体は継続する。1 つの worktree で apply に失敗しても残りの worktree 処理は継続し、失敗 path と exit code は ~/.codex/logs/swt-codex-sync-workspaces.log に集計される。短時間に watch event が連続した場合は wrapper 側で coalesce され、CODEX_WORKTREE_SYNC_DEBOUNCE_SECONDS 以内の再実行は full scan を skip する。未指定時は 120 秒。停止は make stop-codex-workspace-sync、解除は make uninstall-codex-workspace-sync を使う。

sync / cleanup wrapper の ~/.codex/logs/swt-codex-*.log は、起動時に CODEX_WORKTREE_LOG_MAX_BYTES を超えていれば .1 へ rotate する。未指定時の上限は 1 MiB。swt command の出力は CODEX_WORKTREE_LOG_COMMAND_TAIL_LINES 行に抑えられ、未指定時は末尾 80 行だけを残す。

Codex 側で削除済みの worktree に対応する Superset stale record cleanup と、Superset record 起点の stale workspace cleanup は、sync watcher とは別の periodic launchd job として有効化する:

make setup-codex-workspace-cleanup

この target も先に agent-dotfiles import --repo "$(pwd)" --target codex/hooks を実行し、その後 ~/Library/LaunchAgents/com.agent-dotfiles.codex-workspace-cleanup.plist を生成・登録する。cleanup job は WatchPaths を使わず、RunAtLoad と StartInterval だけで swt codex cleanup-archived-workspaces --apply と swt codex stale-workspaces --all --apply --cleanup-sidebar-only を順に定期実行し、Superset v2 renderer localStorage だけに残った sidebar-only workspace も定期 cleanup する。実行間隔は CODEX_WORKTREE_CLEANUP_INTERVAL で上書きでき、未指定時は 300 秒。停止は make stop-codex-workspace-cleanup、解除は make uninstall-codex-workspace-cleanup を使う。

cleanup watcher が起動していても、dirty worktree、current cwd、active thread、open PR、PR state unknown など swt 側の safety gate に該当する workspace は削除されず skip される。実行結果は ~/.codex/logs/swt-codex-cleanup-archived.log で command ごとの start/exit と bounded な command output tail として確認できる。

claude/skills/... を target にした場合も、export 時は ~/.claude/skills/ と ~/.agents/skills/ のうち mtime が新しい側を採用し、import 時は両方へ配布する。teams/、run/、db/messages.db*、db/*.sqlite、db/*.sqlite3 のような skill runtime state は同期対象外。partial target では対象外のファイルやディレクトリは変更されない。

agmsg skill は upstream snapshot と agent-dotfiles overlay から生成して管理する。更新・生成・配布の詳細は agmsg skill の管理を参照する。

claude/agents/... は ~/.claude/agents/ へだけ同期される。Claude Code の subagent 定義を追加・更新した場合は、agent-dotfiles import --target claude/agents/<agent>.md で配布し、Claude Code セッションを再起動してから利用する。

repo 指定

--repo フラグはオプション。省略時は以下の優先順位でリポジトリを自動検出する:

カレントディレクトリが agent-dotfiles リポジトリであればそのまま使用
ghq list から agent-dotfiles を検索

操作対象リポジトリを固定したい場合は --repo を明示する:

agent-dotfiles status --repo /path/to/agent-dotfiles
agent-dotfiles export --repo /path/to/agent-dotfiles
agent-dotfiles import --repo /path/to/agent-dotfiles