同期仕様

管理対象ファイル、Skills 管理、サニタイズ、非管理データ保持、status / diff 表示の見方をまとめる。

管理対象ファイル

管理対象は動的にスキャンされる。各ツールごとにあらかじめ決められた root ファイルおよび特定ディレクトリのみを探索対象とする。また、Codex の config.toml や Copilot の config.json / mcp-config.json など一部の設定ファイルは、別途専用の処理で抽出・管理される。

以下は代表的な repo 側の構成であり、利用状況によって存在しないファイルもある。

agent-dotfiles/
├── claude/                       # Claude Code 設定
│   ├── CLAUDE.md                 # グローバル指示
│   ├── keybindings.json          # キーバインド設定
│   ├── settings.json             # パーミッション・フック設定
│   ├── statusline.py             # ステータスラインカスタマイズ
│   ├── mcp-servers.json          # MCP サーバー設定（~/.claude.json の mcpServers を抽出）
│   ├── agents/                   # カスタムサブエージェント定義
│   ├── commands/                 # スラッシュコマンド（.md ファイル）
│   ├── hooks/                    # フックスクリプト
│   ├── rules/                    # コーディングルール
│   └── skills/                   # スキル定義（~/.claude/skills/ + ~/.agents/skills/ と同期）
├── codex/                        # Codex CLI 設定
│   ├── AGENTS.md                 # エージェント指示
│   ├── config.toml               # Codex 設定（MCP・projects 含む）
│   ├── hooks.json                # フック設定
│   ├── hooks/                    # Codex hook / watcher 補助スクリプト
│   ├── memories/                 # Codex Memories（明示 target のみで backup）
│   └── rules/                    # コーディングルール
├── copilot/                      # Copilot CLI 設定
│   ├── copilot-instructions.md   # エージェント指示
│   ├── config.json               # Copilot 設定（runtime/local state 除外）
│   └── mcp-config.json           # Copilot MCP サーバー設定
├── gemini/                       # Gemini CLI 設定
│   ├── GEMINI.md                 # エージェント指示
│   └── settings.json             # Gemini 設定（MCP env / token 系キーをサニタイズ）
└── superset/                     # Superset ハーネス連携（CLI 管理外）
    └── hooks/
        ├── notify-wrapper.sh                  # Claude フック前段のフィルタ（whitelist 方式）
        ├── install-notify-filter.sh           # Superset の notify.sh に filter を注入（冪等）
        ├── setup-notify-filter-watcher.sh     # launchd でフィルタ再注入を自動化
        ├── stop-notify-filter-watcher.sh      # launchd watcher を停止
        └── uninstall-notify-filter-watcher.sh # launchd 登録を解除

Gemini CLI は利用中の Agent 設定として ~/.gemini/GEMINI.md と ~/.gemini/settings.json のみを管理する。settings.json は JSON として読み、mcpServers.*.env の TOKEN / SECRET / PASSWORD / CREDENTIAL / _KEY 系キーと、その他の token 系キーをプレースホルダ化してから repo に書き出す。import 時は既存の ~/.gemini/settings.json から該当値を復元する。

~/.gemini/google_accounts.json、installation_id、state.json、trustedFolders.json、history/、tmp/ などの認証・履歴・cache・runtime state は管理対象外。import 時も既存の ~/.gemini/ を preseed して保持し、repo 側の管理対象だけを上書きする。Cursor / MastraCode は現時点で利用していないため管理対象外で、dotfiles repo 側には引き続き AI Agent 固有設定を置かない。

Codex Memories

Codex Memories は Codex が過去の作業文脈から生成する state で、主なファイルは ~/.codex/memories/ 配下に置かれる。通常設定とは性質が違うため、codex/memories は PC 移行や明示 backup 用の opt-in target として扱う。target 未指定の export / import / status / diff と --target codex には含めない。

agent-dotfiles export --target codex/memories
agent-dotfiles status --target codex/memories
agent-dotfiles diff --target codex/memories
agent-dotfiles import --target codex/memories

codex/memories では通常テキストファイルだけを同期し、内容中の home path は他の plain file と同じく export 時に {{HOME}} へ置換し、import 時に移行先の home path へ復元する。Codex config.toml / MCP 設定向けの構造化 secret sanitizer は適用しないため、private repository 前提でも commit 前に生成内容へ秘密情報が混入していないか確認すること。

~/.codex/memories/.git、~/.codex/memories/sessions/、*.sqlite、*.sqlite3、*.db、非 UTF-8 の binary file は同期対象外。import --target codex/memories は target 範囲内の stale テキストファイルを repo 側に合わせて削除するが、これらの非管理対象は保持する。

Claude subagent 管理

claude/agents/ は Claude Code のカスタム subagent 定義を管理する通常の Claude 設定ディレクトリ。agent-dotfiles import --target claude/agents/<agent>.md で ~/.claude/agents/<agent>.md に配布し、agent-dotfiles status --target claude/agents/<agent>.md で同期状態を確認できる。

Skills と違い、subagent 定義は ~/.agents/skills/ へ二重配布しない。Claude Code 対話セッション内で使う subagent のため、配布後は Claude Code セッションを再起動して読み込ませる。

Skills 管理

Skills（SKILL.md）は ~/.claude/skills/ と ~/.agents/skills/ の両方を監視し、同じファイルが両方に存在する場合は mtime が新しい側が優先される。mtime が同じ場合は後方互換のため ~/.claude/skills/ が採用される。

エクスポート時: ~/.claude/skills/ + ~/.agents/skills/ → リポジトリ claude/skills/（mtime が新しい側を優先）

インポート時: リポジトリ claude/skills/ → ~/.claude/skills/ + ~/.agents/skills/（両方に書き込み）

export --target claude/skills/<skill> では指定 skill だけを repo に反映し、import --target claude/skills/<skill> では指定 skill だけを ~/.claude/skills/ と ~/.agents/skills/ の両方へ反映する。status コマンドでは claude/skills/... プレフィックスで同期状態が表示され、status --target claude/skills/<skill> で単一 skill だけを確認できる。

Skill 配下で実行時に生成される teams/、run/、db/messages.db*、db/*.sqlite、db/*.sqlite3、.DS_Store は管理対象外。db/config.yaml のような静的な既定設定は通常ファイルとして同期する。

サニタイズ

エクスポート時に以下の変換を自動で行う:

対象	変換
秘匿env値（`TOKEN`, `SECRET`, `PASSWORD`, `CREDENTIAL`, `_KEY`）	`{{ENV_KEY}}` プレースホルダに置換（例: `{{GITHUB_PERSONAL_ACCESS_TOKEN}}`）
ホームディレクトリパス（command, args, env 内）	`{{HOME}}` に置換

インポート時には:

{{HOME}} → 実際のホームディレクトリに復元。Windows 形式の C:\Users\... は管理 JSON/TOML の構文を壊さないよう C:/Users/... のようなスラッシュ区切りへ正規化する
{{ENV_KEY}} → 既存の設定ファイルにある値で復元（新規の場合はプレースホルダのまま）

ツール固有の処理

ツール	MCP 秘匿値の復元元	特殊処理
Claude	`~/.claude.json` の既存値	`mcpServers` のみ上書き、他キーは保持
Codex	`~/.codex/config.toml` の既存値	TOML パースで構造を維持。`[projects]` キーのパスも置換
Copilot	`~/.copilot/mcp-config.json` の既存値	`config.json` の `firstLaunchAt` / `expAssignmentsCache` / `trustedFolders` は環境固有のため除外・保持
Gemini	`~/.gemini/settings.json` の既存値	MCP 秘匿値と token 系キーを復元

エクスポートされないもの

Claude Code

~/.claude/.credentials.json（OAuth トークン）
~/.claude/history.jsonl（会話履歴）
~/.claude/projects/（プロジェクトセッションデータ）
~/.claude/plugins/（プラグインキャッシュ）
~/.claude/todos/（タスク管理データ）
~/.claude/debug/, cache/, file-history/, shell-snapshots/, statsig/, telemetry/ 等のランタイムデータ
ランタイムで生成されるシグナルファイル（claude-signal）
~/.claude.json の mcpServers 以外のキー（統計、キャッシュ等）

Codex CLI

~/.codex/tmp/（一時ファイル）
~/.codex/sessions/（セッションデータ）
~/.codex/archived_sessions/（アーカイブ済みセッションデータ）
~/.codex/*.sqlite（ランタイムDB）
~/.codex/memories/.git, ~/.codex/memories/sessions/, ~/.codex/memories/*.sqlite, ~/.codex/memories/*.sqlite3, ~/.codex/memories/*.db, 非 UTF-8 ファイル（Memories の runtime / binary state）
~/.claude/skills/<skill>/teams/, ~/.agents/skills/<skill>/teams/, run/, db/messages.db*, db/*.sqlite, db/*.sqlite3（Skill の runtime state）

~/.codex/hooks/ は Codex 側の hook 補助スクリプトとして管理対象に含める。agent-dotfiles import --target codex/hooks で配布でき、shell script は実行可能な mode で同期される。launchd 登録そのものは macOS のユーザー環境状態なので、Codex worktree 同期は make setup-codex-workspace-sync、削除済み worktree に対応する Superset stale record cleanup と Superset record 起点の stale workspace cleanup は make setup-codex-workspace-cleanup で ~/Library/LaunchAgents/ に生成する。

sync watcher は WatchPaths と StartInterval を併用し、同じ lock 内で swt codex sync-workspaces --all --quiet の成功後に git worktreeinclude apply --from auto --quiet を実行する。git-worktreeinclude は外部依存として扱い、コピー処理本体は再実装しない。対象 root は WORKTREEINCLUDE_APPLY_ROOTS の : 区切りで指定し、未指定時は CODEX_WORKTREE_SYNC_WATCH_PATH（未指定なら ~/.codex/worktrees）と ~/.superset/worktrees を使う。launchd の WatchPaths には CODEX_WORKTREE_SYNC_WATCH_PATH と WORKTREEINCLUDE_APPLY_ROOTS の各 root を入れるため、Codex / Superset どちらの root に変更があっても同じ wrapper が起動する。WORKTREEINCLUDE_APPLY_FORCE=1 の場合だけ --force を追加する。watch event が短時間に連続した場合は wrapper 側の CODEX_WORKTREE_SYNC_DEBOUNCE_SECONDS で coalesce し、未指定時は 120 秒以内の再実行を full scan せず skip する。git-worktreeinclude 未インストール時や worktree 単位の apply 失敗は ~/.codex/logs/swt-codex-sync-workspaces.log に記録し、sync 自体の成功を失敗扱いに変えない。

sync / cleanup wrapper の ~/.codex/logs/swt-codex-*.log は起動時に CODEX_WORKTREE_LOG_MAX_BYTES を超えていれば .1 へ rotate する。未指定時の上限は 1 MiB。swt command の stdout/stderr は一時ファイルに受けてから CODEX_WORKTREE_LOG_COMMAND_TAIL_LINES 行だけを残し、未指定時は末尾 80 行に抑える。これにより既知の同一失敗や大量 skip summary が毎回 unbounded に append されることを避ける。

cleanup periodic 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 する。cleanup watcher が起動していても、dirty worktree、current cwd、active thread、open PR など swt 側の safety gate に該当する workspace は削除されない。

Copilot CLI

~/.copilot/config.json の firstLaunchAt（環境固有の初回起動タイムスタンプ）
~/.copilot/config.json の expAssignmentsCache（実験割当 cache）
~/.copilot/config.json の trustedFolders（個人の trust 済み workspace 一覧）

インポート時の非管理データの保持

インポート時、管理対象外のディレクトリはインポート前の状態が保持される。

~/.claude/plugins/, file-history/, projects/ 等
~/.codex/tmp/, sessions/ 等

これらはリポジトリに含まれないランタイムデータであり、インポートによって削除されない。管理対象ファイルのみが上書き・削除される。

status の見方

$ agent-dotfiles status
  = claude/CLAUDE.md
  = claude/settings.json
  ~ claude/commands/review-and-fix-pr.md
  + claude/hooks/new-script.js
  - claude/rules/old-rule.md
  = claude/mcp-servers.json
  = claude/skills/my-skill/SKILL.md
  = codex/AGENTS.md
  = codex/hooks.json
  ~ codex/config.toml
  = copilot/copilot-instructions.md
  = copilot/config.json
  ~ copilot/mcp-config.json

記号	意味
`=`	同期済み（リポジトリとシステムが一致）
`~`	変更あり（内容が異なる）
`+`	システムのみに存在（未エクスポート）
`-`	リポジトリのみに存在（未インポート）

MCP 設定（claude/mcp-servers.json / copilot/mcp-config.json）や codex/config.toml などの専用ロジックを持つファイルは、サニタイズ済みの内容同士で比較するため秘匿値やホームパスの違いは無視される。通常の管理ファイルはホームパス置換のみで比較する。

diff の見方

agent-dotfiles diff
agent-dotfiles diff --target codex/config.toml
agent-dotfiles diff --target codex/memories

diff は repo view と system view を normalized tree に書き出してから unified diff を表示する。status と同じ repo display path の --target を受け取り、差分がない場合は No diff. だけを表示する。差分ありはエラー扱いにせず、実行エラーだけを非 0 とする。

MCP 設定、Codex / Copilot / Gemini の構造化設定は export と同じ sanitizer 経路で正規化するため、system 側の raw secret やホームディレクトリの絶対パスは diff に出さない。通常の管理ファイルもホームパスは {{HOME}} に置換してから比較する。Windows 形式の home path は native \、スラッシュ区切り、JSON エスケープ済み \\ の表現差を吸収して比較する。