[Claude Code] · · 16min read

Claude Code 多機同步教學：用兩個 GitHub repo 同步 ~/.claude（claude-self-sync 開源）

三台機器 ~/.claude 設定怎麼同步？Dropbox / iCloud 都會把 chat history 撞壞。claude-self-sync 是一個開源 bash 腳本，把 ~/.claude 拆成公開 config + 私密 secrets 兩個 git repo，三條指令解決多機同步。本文記錄 6 個 macOS / bash / rsync 踩坑與完整安裝步驟。

by 陳彥彤 ·
#Claude Code #claude-self-sync #多機同步 #Git workflow #bash #工程師日常
章節目錄 · 10

# claude-self-sync：用兩個 GitHub repo 同步多台機器的 ~/.claude

TL;DR
我寫了一個 bash 腳本 claude-self-sync，把 ~/.claude 拆成「公開 config」+「私密 secrets」兩個 git repo，三條指令 push / pull / status 解決 Claude Code 多機同步。Dropbox / iCloud 的雷我替你踩過了，所以這個工具預設打開了六道防線。

如果你也是同時用兩台以上電腦在跑 Claude Code 的人——例如家裡 Mac mini + 公司筆電，或常常拉桌機跟筆電換工位——那 ~/.claude 這個資料夾的同步就會變成你日常隱性焦慮的來源。skills 加在 A 機，B 機看不到；memory 在 B 機更新，A 機過幾天忘了改了什麼；某天某個 hook 突然失效，根本不知道是哪一台動到的。

我之前用 Dropbox 同步，結果出事了。所以重新寫了一套。

目錄

  • 為什麼不用 Dropbox / iCloud

  • 兩個 repo 的拆法（為何要拆）

  • 三條指令搞定全部

  • 安全機制：六道防線

  • 為什麼有些東西「故意」不同步

  • 安裝 5 步驟

  • 跟其他方案的差別

  • 常見問題 FAQ

  • 延伸資源

    • 為什麼不用 Dropbox / iCloud

    我一開始也是直接把 ~/.claude 丟進 Dropbox。理由很單純：「同步資料夾不就 Dropbox 嗎？」

    結果踩到三個雷：

    雷 1：雙寫衝突沒救。 Dropbox 兩邊同時改同一個 MEMORY.md，它會默默幫你建 MEMORY (conflict copy from BobAir 2026-04-12).md。等你發現的時候，已經有 17 個 conflict copy 散在 memory 資料夾裡，而你用了某幾天的 MEMORY.md 已經是錯的版本。

    雷 2：HNSW 向量索引炸了。 我有裝 mempalace（Chroma 向量庫），它的 segment 是綁機器的 native 二進位。Dropbox 把 A 機寫到一半的 segment 同步到 B 機，B 機開 mempalace，segfault。

    雷 3：沒有「我反悔了」按鈕。 Dropbox 是 filesystem-level sync，沒有 commit、沒有歷史、沒有 diff。你誤刪一個 skill，它三秒內傳染到所有機器，等你發現已經沒得救（除非翻 Dropbox 三十天垃圾桶，但那是 web UI，路徑跟一堆 random ID）。

    git-based 全部解決： commit 是顯式動作（你要主動 push 才動）、有完整歷史可 revert、有 diff 可看、可以選擇性同步、可以兩個 repo 拆開（公開 + 私密）。

    兩個 repo 的拆法（為何要拆）

    這是 claude-self-sync 跟其他單 repo 方案最大的設計差別。

    RepoVisibility內容
    claude-configpublic（或 private 你決定）skills/ agents/ commands/ rules/ scripts/ hooks/hooks.json
    claude-secrets必須 privateCLAUDE.md settings.json memory/ agent-memory/ services/
    為什麼要拆？
    • skills / agents / commands 是「人類可寫的純配置」——別人看了能用，你也可能想開源（像我這個工具本身）。放 public repo，方便分享、方便 GitHub search 收錄。
    • memory / CLAUDE.md / settings 是「Claude 跟你協作的歷史」——裡面有客戶名稱、API key 殘片、私事、判斷紀錄。絕對不能 public。
    如果用單 repo，你只有兩個選擇：全 public（洩密）或全 private（沒法分享 skill 給別人）。拆兩個 repo，公開私密各得其所。

    順帶一提，claude-self-sync 本身就是從 claude-config 裡的某個 script 抽出來開源的——這個 split 設計實際上就是讓我能做這件事的前提。

    三條指令搞定全部

    sync.sh push              # local → GitHub（commit + push 兩個 repo）
sync.sh pull              # GitHub → local（有 delete 預掃保護）
sync.sh pull --force      # 跳過 delete 預掃（你確認可以刪）
sync.sh status            # 比對 local vs repos，不寫入
sync.sh push --dry-run    # 預覽 push，不寫入
sync.sh pull --dry-run    # 預覽 pull，不寫入

    實際使用節奏：

    • 每天早上開機第一件事： sync.sh pull（拉昨天另一台機器的更新）
    • 每天工作收尾： sync.sh push（推今天的改動）
    • 不確定要不要 push 時： sync.sh status 看 diff
    • 跨機器測試 hook 時： sync.sh pull --dry-run 看會動到什麼
    不需要背任何東西。push、pull、status、dry-run、force——bash 慣例你已經會了。

    安全機制：六道防線

    這不是 cp -r ~/.claude/* ~/repo。每一個防線都對應一個我曾經踩過的真實事件。

    防線 1：Push 用 add-only rsync（沒有 --delete）

    本機誤刪一個檔案不會傳染到 repo。如果你想刪 cross-machine，請去 repo 裡刪，再 pull 下來。

    踩坑來源： 某次清理本機亂檔案，連同某個 hook 一起刪了，push 後 B 機 pull 下來才發現 hook 沒了，已經 commit 在 repo。要 revert 還得回去翻歷史。

    防線 2：Pull 前 delete 預掃 + --force 機制

    pull 預設用 --delete（mirror 模式），但會先掃一遍：「以下檔案會被刪掉：[列表]」。如果有任何刪除，強制要求 --force 才繼續。

    踩坑來源： 某天 pull 之前忘記 push，結果 mirror 模式把今天剛寫好還沒 push 的 sync.sh、3 個 memory 檔、1 個新 skill 全部刪掉。從那天起這個預掃就成了 default。

    防線 3：Pull 前自動 tar.gz 備份

    ~/.claude/backups/sync-pull-{timestamp}.tar.gz，保留最近 3 份。即使 --force 出事，至少有得救。

    防線 4：Push 前 git fetch 檢查

    如果 repo 落後 remote（代表另一台機器先 push 過），拒絕 push。逼你先 pull 合併再 push。避免你覆蓋掉另一台機器的 commit。

    防線 5：mkdir-based mutex

    /tmp/claude-self-sync.lock.d 用 mkdir 原子操作做鎖。同一台機器不會雙跑。macOS 沒有 flock，所以用 mkdir。

    防線 6：openrsync 噪音過濾

    macOS 內建的 openrsync（不是 GNU rsync）偶爾會噴 unlinkat: Directory not empty，但實際傳輸沒問題。rsync_quiet() wrapper 把這類已知非致命警告吃掉，避免你看到 stderr 就以為失敗。

    為什麼有些東西「故意」不同步

    這是「safety-first」哲學的另一面：有些東西就是不該跨機器同步。

    排除原因
    ~/.mempalace/（Chroma 向量庫）HNSW segment 是 single-machine 的 native binary，跨機 sync 會炸索引
    .mcp.json含絕對路徑（每台機器不同），只同步 .mcp.json.example 範本
    巢狀 .git/會把 repo size 撐爆，git 也會搞混
    __pycache__/ *.pyc本機 Python bytecode，沒意義
    .DS_StoremacOS Finder metadata，純垃圾
    node_modules/ .venv/ venv/本機重裝就好，不要塞進 repo
    services 的 .env 和 *.log本機密碼跟 log noise
    每一條 exclude 都是「我曾經把它 sync 過然後出事」的歷史。

    安裝 5 步驟

    # 1. 抓腳本
curl -fsSL https://raw.githubusercontent.com/yanchen184/claude-self-sync/main/sync.sh \
  -o ~/.claude/scripts/sync.sh
chmod +x ~/.claude/scripts/sync.sh

    # 2. 在 GitHub 開兩個空 repo（不要 init README）
    #    https://github.com/new → claude-config（public 或 private）
    #    https://github.com/new → claude-secrets（必須 private！）
    

    # 3. clone 到家目錄
    cd ~ && git clone git@github.com:<你的帳號>/claude-config.git
    cd ~ && git clone git@github.com:<你的帳號>/claude-secrets.git
    

    # 4. 從你的「source of truth」機器第一次 push
    ~/.claude/scripts/sync.sh push
    

    # 5. 在另一台機器 pull
    ~/.claude/scripts/sync.sh pull

    如果 step 5 跑 pull 它會說「以下檔案會被刪掉」，那是因為 B 機有 A 機沒有的本機檔案。兩個選擇：

    • 在 B 機先 push（把 B 的東西先送上去）
    • 確認那些檔案可以丟，跑 pull --force
    整個流程從新機器到 sync 完成，5 分鐘。

    配 Claude Code slash command（選用）

    寫 ~/.claude/commands/sync.md：

    # Sync Claude Config

    Run ~/.claude/scripts/sync.sh $ARGUMENTS and report the result.
    • 空 / "pull" → pull
      •  
    • "push" → push
      •  
    • "status" → status
      •  
    • 帶 --dry-run 或 --force 也轉發
    之後在 Claude Code 裡 /sync push、/sync pull 就能用。

    跟其他方案的差別

    方案機制缺點
    Peter-Moriarty/claude-code-multi-machine-setupDropbox / iCloud filesystem sync雙寫衝突、沒 delete 保護、沒 quality gate
    Plugin marketplace集中式 skill 分發給多人用的，不是給自己多裝置
    stow / chezmoi泛用 dotfile manager不懂 Claude Code 結構（skills vs memory vs agent-memory），不會自動拆公開 / 私密
    手動 cp -r你自己記得跑不會記得；會搞混版本；沒有 history
    claude-self-syncgit + 兩 repo 拆 + 預掃保護macOS / Linux only；要會用 git
    刻意不做的事：
    • ❌ 沒有 GUI、沒有背景 daemon、沒有 cloud service
    • ❌ 不處理 secret rotation、不加密（GitHub private repo 已經夠 personal use）
    • ❌ 不支援 Windows（沒測過，bash 應該大致 work）

    常見問題 FAQ

    Q1：可以多台機器同時 push 嗎？
    不行。Push 前的 git fetch 檢查會擋掉「落後 remote」的 push。手動 pull 合併再 push。雙寫機率本來就低，不值得寫 auto-merge 邏輯。

    Q2：私密 repo 真的安全嗎？
    GitHub private repo 跟你其他私密 repo 一樣安全。前提是你沒不小心開成 public。第一次 push 之前去 repo settings 確認 Visibility: Private 一次。

    Q3：mempalace（向量記憶）為什麼不能 sync？
    向量索引（HNSW）的 segment 是 native binary，跟編譯目標機器綁定。A 機寫到一半的 segment 同步到 B 機 → B 機 mempalace 開起來 segfault。同步 chunk metadata 可以，但 native segments 不行。設計上就排除整個 ~/.mempalace/。

    Q4：pull --force 會把我本機改的東西全部弄掉嗎？
    會。所以才預設要 --force。請務必先看 dry-run 列出要刪的檔案清單，確認那些是你不要的（例如測試殘骸、已經改名的舊檔）才下手。每次 --force 之前 tar.gz 備份還是會跑，最壞還可以解 tar 救回。

    Q5：可以用在 Linux 嗎？
    sync.sh 本身在 Linux 該 work（rsync、bash、git 都有）。launchd plist 那段是 macOS-only，會自動 skip。

    Q6：A 機刪了某個 skill，怎麼讓 B 機也跟著刪？
    push 預設 add-only 不會傳染刪除。正確做法：去 claude-config repo 裡刪那個檔案、commit 到 GitHub，B 機 pull 下來時 delete 預掃會列出它，確認後 pull --force。多兩步，但這是設計就是要逼你「故意」才能跨機刪除。

    延伸資源

    author
    陳
    陳彥彤

    AI 工程師 · AI 顧問。Java 後端 8 年、AI 工程師 2 年。AI 內訓 · AI 導入顧問 · 前後端與雲端培訓。

    support

    覺得文章有用可以到 GitHub 給個 star，或是透過信箱聊聊 AI 內訓、AI 導入顧問或前後端 / 雲端培訓。

    email github
    related

    相關文章

    [Claude Code] · 22min
    我怎麼用 Claude Code 開源一個工具：claude-self-sync 從 271 行 markdown 變獨立 CLI（Ralph Loop 實戰）
    把 ~/.claude/commands/sync.md 內嵌的 271 行 bash 抽出來變成獨立 sync.sh、推到 GitHub、寫 README、發 release。本文記錄整個過程踩到的 6 個 macOS / bash / rsync 雷，以及怎麼用 Ralph Loop + Claude Code 把它從草稿迭代到可用。
    [Claude Code] · 20min
    Superpowers 暴衝 121k stars、Anthropic 收編,該裝嗎?跟手寫 skill 怎麼選
    obra/superpowers 7 個月 121k stars、2026/01 進 Anthropic 官方 plugin marketplace,14 個內建 skill 把資深工程師工作流(brainstorm/TDD/debug)強行套到 Claude Code 上,token -14%、首次成功率 +40%。但我自己跑兩週發現:小任務反而 +20% token、demo 前急著修 bug 被 brainstorming 拖住、Haiku 跑不動。本文拆 14 個 skill 各自解什麼、5 個踩坑、跟自己手寫 skill 的對照表(從適用任務、學習曲線、客製化彈性、維護成本四個維度比較)、Jesse Vincent 的設計哲學(讓 Claude 暫停,不是變聰明)。
    [Claude Code] · 10min
    Claude Code /powerup 完整教學：10 堂互動課程拆解（2026 最新版，本機 binary 為準）
    /powerup 是 Claude Code CLI 內建的互動教學命令，10 堂課掃過最常被忽略的進階功能：subagents、hooks、output styles、permissions、worktrees⋯⋯本文用本機 binary 為 source of truth 逐堂拆解真實內容，附完整指令對照表，新手 1 小時跑完。
    ← all posts