agents-sync

Claude Code と Codex は同じ役割の設定を別々の場所・別々の形式で持つ。放っておくと 片方だけ更新されて食い違う。このスキルはその分裂を解消し、以後ずれないように保つ。

コマンドの呼び方

agents-sync <command> [project] [options]

agents-sync が PATH に無い場合は、このスキルの1つ上の階層にある CLI を直接叩く。 スキルの実体は <clone先>/skill/ にあり、~/.claude/skills/agents-sync と ~/.codex/skills/agents-sync はそこへ辿り着く symlink（片方はもう片方を指す2段リンク）。 CLI は必ず <clone先>/src/cli.ts にある。どちらの登録からでも辿れるよう、 readlink -f で終端まで解決して両方を試す。

SKILL="$(readlink -f ~/.claude/skills/agents-sync 2>/dev/null || readlink -f ~/.codex/skills/agents-sync)"
bun "$(dirname "$SKILL")/src/cli.ts" status

このスキルは Claude Code と Codex のどちらから呼ばれてもよい。 片方のハーネスにしか登録されていなかったら（上の readlink -f が片方だけ成功する状態）、 agents-sync setup で両方への登録状況を見せ、確認を取ってから setup --apply で直す。 登録の向きは --source claude|codex で選べる（既定 claude）。

project を省略するとカレントディレクトリが対象。 書き込みを伴うコマンドは、--apply を付けるまで内容を見せるだけで何も変えない。

CLI は対話しない。 パイプ越しの実行では対話の入力が届かないため、 ユーザーへの質問はすべてこちら（スキル側）が AskUserQuestion で行い、 答えをフラグ（--targets / --source / --no-backup / --from など）で CLI に渡す。 AskUserQuestion が使えないハーネス（Codex など）では、同じ選択肢を 番号付きの箇条書きでチャットに提示し、ユーザーの回答を待ってから進める。

対象と方式

対象	Claude 側	Codex 側	方式
Skills	.claude/skills/<name>/	.agents/skills/<name>	symlink
CLAUDE.md / AGENTS.md	.claude/CLAUDE.md	AGENTS.md	symlink
Hooks	.claude/settings.json の hooks	.codex/hooks.json	双方向変換
MCP	.mcp.json	.codex/config.toml の [mcp_servers.*]	双方向変換
Subagents	.claude/agents/*.md	.codex/agents/*.toml	双方向変換
Rules	.claude/rules/*.md	実ファイル側の指示書に載せる一覧	一覧と適用条件を生成（symlink 経由で共有）

形式が同じものは symlink で1つにする。形式が違うものだけ変換する。

実ファイルをどちら側に置くか（symlink の向き）は、共通設定 source で選べる。 項目ごとではなく、プロジェクト内のすべての symlink 対象に共通で効く。

• claude（既定）… .claude/CLAUDE.md・.claude/skills/ が実ファイル。 AGENTS.md・.agents/skills/ はそこを指す入口
• codex … AGENTS.md・.agents/skills/ が実ファイル。.claude/ 側が入口
• Rules の一覧も実ファイル側の指示書（claude なら CLAUDE.md、codex なら AGENTS.md）へ書き出す

プロジェクト単位の設定

導入すると、対象プロジェクトの直下に .agents-sync.json が作られる。

• targets … 何を同期するか（skills / instructions / mcp / hooks / agents / rules）
• source … 実ファイルをどちら側に置くか（claude / codex。既定 claude）
• backup … 書き換える前にバックアップを取るか（既定 true）
• exclude … このプロジェクトだけの除外指定

このファイル1つで完結する。 マシン全体の設定（~/.config/agents-sync/）が無くても動くので、 「このプロジェクトにだけ入れる」ができる。除外指定だけは両方の足し算になる。

---

ユーザーへの提示の仕方

• まず「何を同期するか」を見せる。 status の先頭に出る「[ 何を同期するか ]」の一覧を、 そのまま箇条書きで伝える。操作の話はそのあと
• 次の一手は、コマンド名ではなく「何を行うか」で提案する。
  • 悪い例: 「agents-sync all --apply を実行 — link はスキップされ、MCP 変換と Rules の書き出しだけが走ります」
  • 良い例: 「差分の無い MCP と Rules を先に同期します（Codex 側の MCP 設定が Claude 側にも反映され、 Rules の一覧が AGENTS.md（CLAUDE.md）に載ります）。中身が違う Skills は、そのあと1件ずつどちらを残すか決めましょう」
  • 対象の呼び方も「指示書」のような言い換えではなく、CLAUDE.md / AGENTS.md・.mcp.json のような 実際のファイル名を使う
  • 実行するコマンドは、提案の末尾に補足として添える程度にする
• 質問は必ず1つずつ。 1回の質問で複数の判断（登録の可否・実ファイル側の選択・一括か個別か、など）を 同時に求めない。1つ答えをもらってから次を聞く。まとめて聞くと、ユーザーは前提の分からないまま 後の質問に答えることになる
• 開発用語を使わない。 diff は「差分」、dry-run は「確認だけ」、conflict は「両方が変わっている」と言う
• 中身が違うものがあるとき、どちらを残すかを最初に聞かない。 まだ差分を見せていない段階の質問では、 「先に差分の内容を確認する（推奨）」を先頭の推奨選択肢にする。 どちらを正とするかの質問と推奨は、差分の中身を確認してユーザーに見せたあとで行う。 中身を見ないうちに片側を推奨してはいけない（新旧や質はパスからは分からない）

最初に: スキル自身の登録を確認する

対象を尋ねる前に、まずこのスキル自身が両ハーネスに登録されているかを確かめる。

agents-sync setup     # 表示のみ。何も書き換えない

• 両方とも登録済みなら、何も聞かずに次へ進む（このステップの存在をユーザーに見せない）
• 未登録・張り替えが必要なものがあれば、その内容を見せて 「マシン共通のスキルとして登録してよいか」を1つの質問として聞く。 よければ agents-sync setup --apply。断られたら登録せずに先へ進む （このセッション中は動くが、次回はもう片方のハーネスから呼び出せない旨を一言添える）

次に「どこへ入れるか」を必ず選んでもらう

登録の確認が済んだら、対象を尋ねる。書き換える範囲がまったく違い、 取り違えると影響範囲が一気に広がるため、勝手に決めない。

Claude Code では AskUserQuestion を使い、次の3つを、この順・この文言で提示する。 Codex など AskUserQuestion が無いハーネスでは、同じ3つを番号付きでチャットに提示して選んでもらう。

選択肢（そのまま提示する文言）	何をするか
特定のプロジェクト内への導入（推奨）	1つのプロジェクトだけを対象にする。.agents-sync.json がそのプロジェクトの中に作られ、他には一切影響しない
グローバル設定の変更	~/.claude と ~/.codex（全プロジェクト共通の設定）を対象にする
全プロジェクトへの導入（まずは特定のプロジェクトで試してください。時間が掛かります）	マシン全体を走査し、見つかったプロジェクトを1件ずつ片付ける

尋ねずに進めてよいのは、依頼文が対象を明示している場合だけ（「このリポジトリを同期して」 「~/.claude と ~/.codex を見て」「全部のプロジェクトを片付けて」など）。 「同期して」「分裂を解消して」のように対象が書かれていなければ、必ず聞く。

選択後の進め方:

• 「特定のプロジェクト内への導入」→ 下の A
• 「グローバル設定の変更」→ global.md の B
• 「全プロジェクトへの導入」→ global.md の C

A. 特定のプロジェクト内への導入（推奨）

対象のプロジェクトが依頼文から分からなければ、パスを聞く。省略時はカレントディレクトリ。

まず .agents-sync.json の有無で入口が変わる。

agents-sync status <project>    # 読み取りのみ。未導入ならその旨が出る

未導入の場合 — 導入ウィザード。この順番で、質問は1段ずつこちらが行い、答えを CLI に渡す。 ユーザーの代わりに答えを決めない。

1. 差分の洗い出しを見せる（表示のみ）。 agents-sync status <project> を実行し、「[ 何を同期するか ]」の一覧をそのまま見せる。 この時点では何も聞かず、何も書き換えない
2. 何を同期するかを聞く（複数選択）。選択肢には 1 の差分状況を添え、 項目は「指示書」のような言い換えではなく 実際のファイル名で示す （Skills、CLAUDE.md / AGENTS.md、MCP（.mcp.json / .codex/config.toml）、Hooks、Subagents、Rules）。 あわせて 「ここではまだ同期しません。差分がある項目をどう統合するかは、このあと1項目ずつ確認します」と明記する。 既定は全部入
3. 実ファイルをどちら側に置くかを聞く（symlink の向き。項目ごとではなく共通の設定）。 次の解説を必ずセットで添える: 「実ファイル側を選ぶと、もう片方は同じ内容を参照する symlink になるため、以後の設定更新が分岐しません。 symlink が張られるのは、先ほど選んだ同期項目だけです」 （すべてが勝手にリンクされるわけではない、と伝えるための解説。省略しない）
   • Claude 側（推奨）… .claude/CLAUDE.md・.claude/skills/ が実ファイルになる
   • Codex 側 … AGENTS.md・.agents/skills/ が実ファイルになる 「ふだん設定を編集するハーネスの側に置くとよい」と添える。迷っていたら既定の Claude 側
4. 差分がある項目について、どのように統合するかを1項目ずつ聞く。 2 で選ばれた項目のうち、中身が違う・両方が変わっているものだけが対象。 項目ごとに差分の中身を見せてから、どちらの内容を残すか（または個別にどう扱うか）を聞く。 1回の質問で複数の項目をまとめて聞かない。 差分の無い項目についてはこの質問をしない
5. バックアップを取るかを聞く（既定: 取る）。取っておくと agents-sync restore で 実行前の状態に戻せる、と添える
6. 設定を書いて実行する。

   agents-sync init <project> --targets skills,instructions,mcp,hooks,agents,rules --source claude
   

   選ばれた対象だけをカンマ区切りで渡す。バックアップを取らない場合のみ --no-backup を付ける。 4 で「残す」と決めた内容を 3 で選んだ実ファイル側に置いてから （変換対象の両方変わっているものは sync --only <id> --from <側> を使う）、 agents-sync all <project> で確認だけ出し、「何を行うか」ベースで内容を伝えて、 実行してよいか聞く。よければ agents-sync all <project> --apply
7. 自動同期を使うかを聞く（macOS のみ）。選択肢は3つ:
   • 使わない（既定）… 何もしない。変更したときに手動で同期する
   • まずお知らせだけ受け取る … agents-sync repos add <project> を実行し、 agents-sync watch --notify-only を案内する（書き込まず通知だけ）
   • 自動で反映する … agents-sync repos add <project> → agents-sync install-daemon

導入済みの場合 — resolve.md の 「ウィザード: 分裂しているプロジェクトを1つ解決する」を Step 0 から回す。

このモードが既定の推奨なのは、影響範囲がそのプロジェクトの中で閉じているため。 うまくいかなければ agents-sync restore でそのプロジェクトだけ元に戻せる。

---

元に戻す

backup が有効なら、書き換える前の状態が <project>/.agents-sync/backups/ にある。

agents-sync restore                    # バックアップの一覧
agents-sync restore <id>               # 何が戻るかを確認
agents-sync restore <id> --apply       # 実際に戻す

• 書き戻すだけでなく、その操作で新しく作られたものも消すので実行前の状態に戻る
• 1回の実行はまとめて1つの復元点になる（all で3処理が走っても復元は1回）
• 常駐による反映は、反映1回ごとに別の復元点になる（古いものから20件を超えると間引かれる）

ユーザーが「元に戻して」と言ったら、まず restore で一覧を出し、 どの時点に戻すかを確認してから --apply する。

---

詳細な手順（必要になったら読む）

場面	参照
導入済みプロジェクトの分裂解決（Step 0〜6）、scaffold、新規プロジェクト直後	resolve.md
グローバル設定の変更（B）、全プロジェクトへの導入（C）、片側非対応の除外原則	global.md
常駐（自動同期）の導入・対象の追加・停止	daemon.md

---

守るべきこと

• 依頼範囲が曖昧なら、規定されたステップを省略しない。 「導入して」「同期して」のように、どこまで行うかが明示されていない依頼では、対象モードで定めた手順を最初から最後まで順番に進める。任意機能（導入後の自動同期など）も、不要と推測して勝手に飛ばさず、規定どおり利用するかを確認する。ユーザーが「手動同期まで」「常駐化は不要」などと明示した場合にだけ、その範囲外のステップを省略できる
• 入口側（symlink）を直接編集しない。 実ファイルは source で選んだ側にある （既定 claude: .claude/skills/*・.claude/CLAUDE.md）。片方だけ編集するという概念は無い
• .codex/agents/*.toml を直接編集しない。 .claude/agents/*.md を直して同期する。 .toml 内の <!-- agents-sync:meta --> マーカーを消すと往復できなくなる
• .claude/worktrees/ には絶対に触らない。 別ブランチの作業ツリーで、 触ると他ブランチに未コミット差分が生まれる
• 「両方が変わっている」を自動解決しない。 どちらを採用するかは必ずユーザーに聞く
• 「実ファイルを置く側へ移す」が出たら鮮度を確認する。 ツールは新旧を見ていない。 移す前に両側の中身と更新経緯を確認し、どちらが新しいかをユーザーと確定させる
• --prune は明示的に頼まれたときだけ使う
• 作業前に、既存の未コミット変更と自分の変更を混ぜないこと（git を使っている場合）
• ユーザーに説明するときは、diff / dry-run / conflict のような語をそのまま使わず、 CLI が出す言葉（差分 / 確認だけ / 両方が変わっている）に合わせる
• <!-- agents-sync:rules:start --> 〜 end の中を手で編集しない。 次回の実行で上書きされる。 直すのは .claude/rules/ のファイルのほう