agents-sync

Claude Code と Codex に分かれてしまった設定を、1つにまとめて、以後ずれないように同期するツールです。

CLAUDE.md と AGENTS.md、.claude/skills/ と .agents/skills/ のように、 同じ内容が2か所に置かれていると、使用するコーディングエージェントごとに設定が独自に分岐していってしまいます。(= 意図した分岐であればよいですが、片方の変更がもう片方に同期されない、ということが起きます)
agents-sync は、片方を実ファイル・もう片方をSymlink(同じファイルを参照させる)にすることで、この分岐をなくします。

対応ツール / モード

インストール

一度だけ行う作業です。

1. ダウンロードする

ZIP をダウンロード

ダウンロードした ZIP を展開してください。置き場所はどこでも構いません。

2. セットアップする

展開したフォルダをそのままClaude CodeまたはCodexに渡して、「これを導入して」と指示してください。どちらに渡しても構いません。 セットアップは両方のツールに登録するので、以後はClaude CodeとCodexのどちらからでも呼び出せます。

エージェント向けの手順: 展開先のフォルダで bun src/cli.ts setup を実行して登録状況を表示し、内容をユーザーに見せて確認を得てから bun src/cli.ts setup --apply で登録します。登録の向きはスキル同期と同じ規約です。~/.claude/skills/agents-sync が展開先の skill/ フォルダを指し、~/.codex/skills/agents-sync はその ~/.claude/skills/agents-sync を指します（実体は展開先の1つだけ）。

注意：スキルはマシンに1つだけ入れる

agents-sync は、マシンに1つだけ入れる前提のスキルです。 対象が1つのプロジェクトだけであっても、プロジェクトの中にコピーせず、上記のセットアップ（~/.claude/skills/ と ~/.codex/skills/ への登録）を使ってください。

• 中身がプロジェクトに依存しません … 書かれているのは agents-sync の操作手順で、 どのプロジェクトでも同じです。プロジェクトごとに変わるのは設定ファイルです
• プロジェクトに置くと、自分自身が同期対象になります … .claude/skills/agents-sync/ に置くと、 agents-sync がそれを .agents/skills/ へリンクし、ツールの説明書がそのリポジトリに コミットされてしまいます
• プロジェクトに置くと、agents-sync 自身が居場所を見失います … スキルは ~/.claude/skills/agents-sync（または ~/.codex/skills/agents-sync）を手がかりに、自分の本体がどこにあるかを割り出しています

操作の流れ

セットアップ後、エージェントに実行を頼むと、以下の流れで作業を進めてくれます。

最初に、どこへ入れるかを聞かれます

対象によって書き換える範囲がまったく違うため、実行前に聞かれるようになっています。

初めて使うときは、特定のプロジェクト内への導入から始めるのが安全です。 影響がそのプロジェクトの中で閉じているので、気に入らなければそこだけ元に戻せます。

次に、いまの差分が表示されます

まず、Skills・CLAUDE.md / AGENTS.md・MCP などの項目ごとに、 両ツールの設定がどれだけ食い違っているかの一覧が表示されます。ここでは表示だけで、まだ何も変わりません。

何をまとめるかを聞かれます

一覧を見たうえで、まとめる対象を選べます。すべてそのままで進めても、安全な既定になっています。 この時点ではまだ同期されません。

次に「実ファイルをどちら側に置くか」を聞かれます。項目ごとではなく、プロジェクト共通の設定です。 Claude 側（.claude/CLAUDE.md・.claude/skills/）が既定で、Codex 側（AGENTS.md・.agents/skills/）も選べます。 実ファイル側を選ぶと、もう片方は同じ内容を参照する symlink になるため、以後の設定更新が分岐しません。 symlink が張られるのは、選んだ対象だけです。ふだん設定を編集するツールの側に置くのがおすすめです。

中身が食い違っている項目があれば、続けて1項目ずつ、差分の内容を見ながらどちらを残すかを聞かれます。 質問は1つずつ順番に来るので、まとめて判断を迫られることはありません。

最後に「書き換える前にバックアップを取りますか」と聞かれます。取っておくと、 あとから「元に戻して」と言うだけで実行前の状態に戻せます。

実行する前に、必ず内容が表示されます

いきなり書き換えられることはありません。何がどう変わるか、元に戻せるかが先に表示されます。

→ .agents/skills/bar
     実ファイルを置く側へ移す — ファイルそのものを実ファイルを置く側へ移し、
     もう片方はそこを指す入口になります
     ファイルが移動・削除されます（バックアップから戻せます）
→ AGENTS.md
     symlink を作る — 実ファイルを置く側にあるものを、もう片方からも
     同じものとして開けるようにします
     元に戻せます（作り直すだけ）

内容を確認したうえで、進めてよいかを聞かれます。

まとめられるもの

形式が同じものは symlink で1つにします。形式が違うものだけ変換します。
実ファイルをどちら側に置くかは選べます。既定は Claude 側（.claude/CLAUDE.md・.claude/skills/）で、 Codex 側（AGENTS.md・.agents/skills/）はそこを指すようになります。 Codex 側に置く設定にすると、向きが逆になります。 どちらにしても、編集するのはいつでも実ファイル側の1か所だけで済むようになります。

何をまとめるかは項目ごとに制御が可能です。

symlink は1つのファイルを2か所から開けるようにする仕組みで、 どちらから開いても中身は同じ1つのファイルになります。

Rules だけ扱いが違います

Claude Code は .claude/rules/*.md をハーネスの機能として自分で読み込みます。 paths: が書いてあれば該当ファイルを触ったときだけ、無ければ毎回読みます。 Codex にはこの仕組みがありません（.codex/rules/ はコマンド承認ポリシー用で、別物です）。

そこで agents-sync は、ルールの**一覧と「いつ読むべきか」**を、実ファイルを置く側の指示書（既定では CLAUDE.md）の管理ブロックに書き出します。 もう片方は symlink なので、実ファイルは1つのまま両方のツールに届きます。

| ルールファイル | 読むタイミング |
|---|---|
| `.claude/rules/api.md` | `src/api/**/*.ts` を扱うとき |
| `.claude/rules/code-style.md` | 常に |

中身そのものは展開しません。paths: 付きのルールを全文展開すると、 条件付きだったものが常時適用に変わってしまうためです。 どのルールをいつ読むかを伝えて、実際に読むかどうかは読み手のツールに委ねます。

元に戻す

「元に戻して」と伝えると、バックアップの一覧が出て、どの時点に戻すかを選べます。

戻すときは、書き戻すだけでなくその操作で新しく作られたものも消すので、実行前の状態になります。 1回の操作はまとめて1つの復元点になるので、何度も選び直す必要はありません。

バックアップは、そのプロジェクトの中の .agents-sync/backups/ に入っています。

自動同期（macOS のみ）

「これから自動で同期して」と言うと、設定ファイルの変更を検知して、 片側だけが変わっていれば自動でもう片方へ反映するようになります。 両側とも変わっていたときは書き込まず、通知で知らせます。

いきなり自動で書き込ませるのが不安な場合は、まずお知らせだけ受け取る設定を選べます。 数日ようすを見てから、自動で反映する設定に切り替えられます。

あとから対象のプロジェクトを増やすとき

「このプロジェクトも自動同期の対象にして」と伝えます。 登録だけでなく、自動同期の読み込み直しまで行う必要があります。

自動同期は起動したときに対象一覧を1回読むだけで、あとはそのまま監視し続けます。 動いている最中に登録を足しても、そのままでは新しいプロジェクトを見ていません。 読み込み直すと、最新の一覧で動き始めます。対象から外すときも同じです。

なお、対象が勝手に増えることはありません。導入時に「自動で反映する」を選んだプロジェクトと、 あとから明示的に足したプロジェクトだけが対象になります。

プロジェクトごとの設定ファイル

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

• 何を同期するか
• 実ファイルをどちら側に置くか（symlink の向き）
• 書き換える前にバックアップを取るか
• 個別に同期しないもの（除外指定）

このファイル1つで完結します。 他のプロジェクトには影響しませんし、 チームで共有すれば全員が同じ設定になります。

設定ファイルの正典

前回同期したときの記録を残しておき、「前回と変わった側」を変更された側とみなします。 ファイルの更新時刻は git checkout や別のツールでも動いてしまうため、使いません。

削除は既定では行われません。明示的に指示したときだけ、 片側から消えたものをもう片方でも消します。

片側が対応していないものは、同期しません

「両側にあるべきなのに片方だけ」は食い違いですが、 「片方のハーネスが機能的に対応していない」のは仕様です。 後者を無理にそろえると、動かない設定が増えるだけで害になります。

「これは同期しないで」と伝えると、理由とあわせて除外指定に登録できます。 既定ではそのプロジェクトの設定に、指定すればマシン全体の設定に書き込まれます。

既知の非対応:

• SessionEnd フック … Codex に同じ場面が存在しません。Claude 側だけで持ちます
• マシン全体のフック … 設定の文字列だけそろえても、呼び出されるスクリプトの実体は付いてきません
• Codex のマシン全体の外部ツールの一部 … node_repl などは Codex 内部のもので、Claude へ流すのは誤りです

設計上の制約

• Bun の TOML パーサーは仕様から外れています。 複数行文字列の開始 """ 直後の改行を 削除しません（TOML 仕様では削除します）。Codex が使う Rust のパーサーは仕様どおりなので、 同じファイルから読める文字列が1文字ずれます。読み込み時に前後の空白を正規化して吸収しています
• Codex の外部ツール設定は、キーの有無で通信方式を推論します。 url があれば HTTP、command があれば stdio です。Claude 側の "type": "http" に相当する キーが無いので、変換時に落として復元しています
• .codex/config.toml は全体を作り直しません。 [mcp_servers.*] のところだけ差し替えます。 model や approval_policy などの他の設定とコメントを壊さないためです
• JSON も書式を再現します。 JSON.stringify(x, null, 2) は配列を必ず改行展開するため、 短い配列だけ1行に収める整形器を持っています（意味のない差分を出さないためです）
• .claude/worktrees/ は自動同期の対象にしません。 別ブランチの作業ツリーであり、 触ると他のブランチに未コミットの変更が生まれます

symlink と git

git は symlink をモード 120000 の blob（中身はリンク先の相対パス文字列）として記録します。 そのまま版管理でき、clone や checkout で復元されます。 相対パスで張ることが大切です（絶対パスだと別のマシンで壊れます）。

Windows で clone する場合、開発者モードが無効だと symlink がただのテキストファイルとして 展開される点には注意が必要です。

備考：CLI

ふだん意識する必要はありませんが、スキルは内部で agents-sync コマンドを実行しています。 うまく動かないときの切り分けに使えます。

--apply を付けるまでは、どのコマンドも内容を表示するだけで、ファイルには触れません。

使用する外部ライブラリ

ライセンス

MIT License です。詳細は LICENSE を参照してください。

作者

• X: @kanta_tkd
• GitHub: devsprotein