Claude Code Multi-Machine Setup

Sync your Claude Code configuration across multiple macOS machines using iCloud, with automatic dependency checking at session start.

The Problem

Claude Code stores configuration in ~/.claude/, including:

• CLAUDE.md - Global instructions
• claude.json - MCP server configurations
• settings.json - Hooks, permissions, plugins
• commands/, skills/, agents/, hooks/

When using multiple machines, you want this config synced. But some dependencies (like local MCP server builds and Playwright browsers) need to be set up on each machine individually.

The Solution

1. Symlink ~/.claude to iCloud - Config syncs automatically
2. SessionStart hook - Warns when local dependencies are missing
3. Bootstrap script - One command to set up a new machine

Quick Start

1. Set Up iCloud Sync (One Time)

On your first machine, move your Claude config to iCloud:

# Move existing config to iCloud
mv ~/.claude ~/Library/Mobile\ Documents/com~apple~CloudDocs/claude-shared-config

# Create symlink
ln -s ~/Library/Mobile\ Documents/com~apple~CloudDocs/claude-shared-config ~/.claude

On additional machines, just create the symlink (iCloud syncs the folder):

ln -s ~/Library/Mobile\ Documents/com~apple~CloudDocs/claude-shared-config ~/.claude

2. Add the Dependency Check Hook

Copy hooks/check-deps.sh to ~/.claude/hooks/:

cp hooks/check-deps.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/check-deps.sh

Register it in ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/check-deps.sh"
          }
        ]
      }
    ]
  }
}

3. Set Up the Bootstrap Script

Copy setup.sh to your MCP servers directory:

mkdir -p ~/mcp-servers
cp setup.sh ~/mcp-servers/
chmod +x ~/mcp-servers/setup.sh

Customize setup.sh with your MCP servers (see comments in file).

4. Bootstrap New Machines

When you set up a new machine:

# 1. Create the symlink (config syncs via iCloud)
ln -s ~/Library/Mobile\ Documents/com~apple~CloudDocs/claude-shared-config ~/.claude

# 2. Clone your MCP server repos to ~/mcp-servers/

# 3. Run the setup script
~/mcp-servers/setup.sh

How It Works

iCloud Sync

The symlink makes ~/.claude point to an iCloud folder:

~/.claude -> ~/Library/Mobile Documents/com~apple~CloudDocs/claude-shared-config

Everything in this folder syncs automatically across your Macs.

What Syncs vs What's Local

Syncs via iCloud	Requires Local Setup
CLAUDE.md	MCP server repos (~/mcp-servers/)
claude.json	node_modules in each server
settings.json	Built artifacts (dist/)
hooks/, commands/, skills/	Python venvs
agents/, plugins/	Playwright browsers

The SessionStart Hook

When you start a Claude Code session, check-deps.sh runs and checks:

1. Playwright browsers - Required for web automation MCP
2. Node.js MCP servers - Checks for clone, node_modules, and dist/
3. Python MCP servers - Checks for clone and .venv/

If anything is missing, it shows a warning with the fix command:

DEPS (My-MacBook): Missing local dependencies:

  - my-server not built
    Fix: cd ~/mcp-servers/my-server && npm run build

Or run full setup: ~/mcp-servers/setup.sh

The check is non-blocking - you can still use Claude Code, but the warning reminds you to fix it.

Customization

Adding MCP Servers to check-deps.sh

Edit ~/.claude/hooks/check-deps.sh and add calls to the check functions:

# Node.js servers
check_node_server "my-server" "https://github.com/user/repo.git"

# Python servers
check_python_server "my-python-server"

Adding Servers to setup.sh

Edit ~/mcp-servers/setup.sh and add calls:

# Node.js servers
setup_node_server "my-server" "https://github.com/user/repo.git"

# Python servers
setup_python_server "my-python-server"

Files

.
├── README.md                    # This file
├── setup.sh                     # Bootstrap script for new machines
├── hooks/
│   └── check-deps.sh           # SessionStart hook for dependency checking
└── templates/
    └── CLAUDE.md               # Template for multi-machine CLAUDE.md section

Requirements

• macOS with iCloud Drive enabled
• Claude Code installed
• Node.js and npm (for Node.js MCP servers)
• Python 3 (for Python MCP servers)

License

MIT