Đồng bộ cấu hình Claude Code (CLAUDE.md, skills, plugin, MCP) giữa nhiều máy tính bằng cclayer, tách danh tính git theo từng nhóm

Dùng Claude Code lâu, trong ~/.claude sẽ tích lại khá nhiều thứ: CLAUDE.md toàn cục, đủ loại rules, skills, hooks, quyền và plugin trong settings.json, thêm cả đống MCP server. Tôi thường dùng Claude Code trên mấy máy tính, máy nào cũng phải cấu hình lại từ đầu. Sửa chút quy tắc ở máy này thì các máy khác cũng phải sửa tay theo, lâu dần cấu hình giữa các máy không còn khớp nhau nữa.

Phiền hơn nữa là dự án đến từ nhiều nhóm khác nhau. Mỗi nhóm có danh tính commit git (tên người dùng, email) riêng, có nhóm còn có rules và hook riêng. Những thứ này chỉ nên có hiệu lực trong dự án của nhóm đó, không được lẫn sang dự án khác, càng không được để email công ty bị commit vào repository mã nguồn mở của chính mình.

Ném thẳng ~/.claude vào một git repository cũng không ổn: trong đó có trạng thái đăng nhập, lịch sử phiên làm việc, thiết lập quyền của riêng máy đó, còn đồ của nhóm thì không thể đưa vào repository công khai. Vì vậy tôi viết cclayer để giải quyết đúng vấn đề này.

cclayer là gì

cclayer tách cấu hình Claude Code thành hai loại “lớp” (layer):

• Lớp nền (base): những thứ giống nhau trên mọi máy, gồm CLAUDE.md, rules/, skills/, output-styles/, agents/, script hook, các khóa dùng chung trong settings.json, danh sách plugin và marketplace, định nghĩa MCP. Bên trong không có bất kỳ thông tin danh tính nào, nên có thể để trong repository công khai.
• Lớp phủ (overlay): mỗi nhóm một lớp, chứa danh tính git của nhóm đó, hook, quy tắc địa chỉ repository (ví dụ github.com/acme-inc/*), cùng với .claude/settings.local.json và CLAUDE.local.md sẽ được ghi vào các dự án đó. Lớp phủ chỉ có hiệu lực trong các dự án khớp quy tắc, và không ghi bất cứ thứ gì vào ~/.claude.

Mỗi máy chỉ kéo lớp nền cộng với những lớp phủ nó cần. Một lệnh cclayer apply là trải xong mọi thứ, một lệnh cclayer push là đẩy thay đổi trên máy này lên lại.

Lớp có thể là git repository, cũng có thể chỉ là một thư mục nằm trong thư mục đồng bộ của ổ đĩa đám mây, không muốn đụng tới git vẫn dùng được.

Cài đặt

macOS dùng Homebrew:

1
brew install --cask zhaojiannet/tap/cclayer

Nâng cấp về sau:

1
brew upgrade --cask cclayer

Linux và Windows thì tải file binary ở trang Releases. Cần cài sẵn git; các bước liên quan đến plugin và MCP cần Claude Code 2.1.288 trở lên.

Cách dùng đơn giản nhất: một người, vài máy tính

Nếu không có nhóm nào cần tách riêng thì một lớp nền là đủ.

Máy đầu tiên

1
cclayer setup

setup là giao diện cấu hình toàn màn hình. Cột trái là các lớp và thiết lập của máy này, cột phải là phần giải thích mục đang chọn và các trường có thể sửa. Trước khi bấm lưu sẽ không có file nào bị ghi. Chữ trên giao diện hỗ trợ tiếng Trung giản thể, tiếng Anh và tiếng Nhật, mặc định theo ngôn ngữ hệ thống.

Chỉ cần điền hai mục:

1. Lớp nền: điền một thư mục (ví dụ ~/Dropbox/cclayer/base trong ổ đĩa đám mây) hoặc địa chỉ một git repository riêng tư. Nếu thư mục chưa tồn tại, khi lưu sẽ tự tạo file layer.toml khởi đầu.
2. Thư mục dự án: thư mục chứa code, ví dụ ~/Projects.

Chọn “Save and apply”, rồi gom cấu hình hiện có của máy này vào lớp:

1
cclayer capture --add CLAUDE.md --add rules/ --add skills/

Đường dẫn là tương đối so với ~/.claude. Trước khi gom vào, từng file sẽ được kiểm tra một lượt, những thứ như khóa bí mật, email, đường dẫn tuyệt đối trỏ tới thư mục home của máy này sẽ bị chặn lại, kèm theo số dòng. Nếu chỉ mình bạn dùng và lớp cũng để ở chỗ riêng tư, thêm một dòng private = true dưới [layer] trong layer.toml là sẽ không chặn email nữa.

Các máy khác

Cài cclayer, cũng chạy cclayer setup, lớp nền điền cùng địa chỉ, lưu và áp dụng, cấu hình của máy đầu tiên sẽ sang đủ. Những file đã có trên máy này nhưng nội dung khác sẽ được liệt kê ra để hỏi bạn có ghi đè không, trước khi ghi đè file cũ sẽ được sao lưu vào ~/.local/state/cclayer/backups/.

Đồng bộ hằng ngày

Nếu dùng git repository làm lớp:

1
cclayer push          # Tải lên: gom thay đổi trên máy, liệt kê nội dung sẽ commit, xác nhận xong thì commit và push
2
cclayer apply --pull  # Tải xuống: kéo lớp mới nhất, rồi trải ra máy này

Nếu dùng thư mục ổ đĩa đám mây làm lớp thì việc đồng bộ do ổ đĩa đám mây lo, sửa xong chạy cclayer capture, máy kia chạy cclayer apply là được.

Bạn còn có thể đặt SessionStart hook dưới đây vào claude/settings.json của lớp nền, rồi bật “Auto pull” trong setup. Từ đó mỗi lần mở phiên Claude Code sẽ tự động kéo và áp dụng:

1
{
2
  "hooks": {
3
    "SessionStart": [{
4
      "matcher": "startup",
5
      "hooks": [{ "type": "command", "command": "command -v cclayer >/dev/null && cclayer apply --hook || true" }]
6
    }]
7
  }
8
}

Cấu hình danh tính git khác nhau cho từng nhóm

Đây là lý do chính khiến tôi viết cclayer. Trước tiên tạo một repository riêng tư cho nhóm, ở thư mục gốc đặt một file layer.toml, ghi rõ danh tính và các repository cần khớp:

1
[layer]
2
name = "acme"
3
kind = "overlay"
4

5
[identity]
6
name = "Full Name"
7
email = "me@acme.example"
8

9
[[match]]
10
remote = "github.com/acme-inc/*"

Sau đó thêm lớp phủ này trên máy cần dùng. Nó sẽ hỏi bạn cấu hình thông tin xác thực truy cập repository thế nào, rồi clone về và kiểm tra một lượt:

1
cclayer layer add acme git@github.com:you/cclayer-acme.git

Sau khi apply, cclayer sẽ thêm một khối include vào cuối ~/.gitconfig, dùng includeIf "hasconfig:remote.*.url:..." của git để danh tính này chỉ có hiệu lực trong các repository có địa chỉ remote khớp github.com/acme-inc/*, nội dung vốn có trong ~/.gitconfig hoàn toàn không bị động tới. Khi để trống danh tính mặc định (default_identity), git sẽ từ chối commit ở những repository không khớp lớp phủ nào, sẽ không còn chuyện commit nhầm email nữa.

Quy tắc khớp phải ghi rõ host và tổ chức, không được dùng ký tự đại diện thay thế, để tránh lớp phủ của nhóm này nhận nhầm repository của nhóm khác.

Nếu muốn đăng nhập, phiên làm việc và lịch sử prompt của Claude Code giữa các nhóm cũng tách biệt hoàn toàn, có thể bật chế độ profiles. Mỗi lớp phủ sẽ có thư mục cấu hình riêng ở ~/.claude-profiles/<tên-lớp>, cclayer env xuất ra CLAUDE_CONFIG_DIR tương ứng, kết hợp với direnv thì vào dự án nào dùng bộ cấu hình của dự án đó.

Về mặt bảo mật

hook và skills được đồng bộ về đều sẽ được Claude Code thực thi trên máy, nên cclayer khá thận trọng ở khoản này:

• Những thiết lập có thể chạy chương trình hoặc bật plugin như hooks, statusLine, enabledPlugins, cùng các file trong hooks/, skills/ và file có quyền thực thi, trước khi ghi đều được liệt kê nội dung để bạn xác nhận. Cùng một nội dung đã xác nhận một lần thì không hỏi lại.
• Đoạn cấu hình git chỉ cho qua các thiết lập thông dụng như pull.rebase, push.default. Các khóa có thể chạy chương trình như alias, core.hooksPath, credential.helper chỉ được phép khi lớp đó được tin cậy rõ ràng trong danh sách thiết bị.
• Trạng thái đăng nhập của Claude Code, history.jsonl, projects/ sẽ không bị đọc vào lớp; permissions.allow và env được giữ lại trên máy.
• Trong lớp không được có symbolic link, khi ghi file cũng không đi theo symbolic link.

Các lệnh hay dùng

Cách dùng chi tiết hơn, bao gồm cách tạo git repository, thông tin xác thực cho repository riêng tư và các câu hỏi thường gặp, xem hướng dẫn cclayer (bằng tiếng Anh).

Địa chỉ dự án trên GitHub: https://github.com/zhaojiannet/cclayer