← Blog

Sharing Claude Code config across two Macs (and letting them diverge)

· 4 min read

Contents
  1. The setup
  2. Where I stopped trying to share
  3. What sharing is actually for
  4. What I'd do differently
  5. The deliberate divergence

I run Claude Code on two machines. A MacBook Air I carry around, and a Mac Mini that sits in the corner of my flat running seven agents and an LLM behind a Cloudflare Tunnel. The same ~/.claude/CLAUDE.md should define how Claude behaves on both. The same settings.json should ideally apply too.

For a while I tried to keep them in lockstep by hand, copy-pasting changes from one machine to the other. It worked for about a week.

The fix turned out to be one symlink and one concession.

#The setup

I have a folder in iCloud Drive at ~/Library/Mobile Documents/com~apple~CloudDocs/claude-config/. It holds two files: CLAUDE.md and settings.json. iCloud syncs that folder across both Macs by default. On each machine, ~/.claude/CLAUDE.md is a symlink into the iCloud folder.

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

Edit the file on the Air, save, walk to the Mini, the change is already there. The ethos rules, the verification habits, the deployment workflow, every "MUST not do X" I've collected over the past few months, all of it lives in one place and applies to both machines.

That part was the obvious half. The non-obvious half was settings.json.

#Where I stopped trying to share

settings.json is where Claude Code keeps machine-specific configuration: which hooks fire, which tools auto-allow, which voice transcription you've enabled, what theme. My first instinct was the same as with CLAUDE.md. Symlink it, share it, done.

That's the wrong shape.

The two machines do different things:

  • Mac Mini is always on, plugged in, runs my voice setup, drives OpenClaw, has tmux-aware hooks because most of its sessions are over SSH from elsewhere.
  • MacBook Air is the device I open a session on for an hour at a time. It has autocompact, my full superpowers skill set, and the safety hooks I want when I'm editing code in a hurry on the couch.

If I'd kept these in sync I'd have ended up with the union of both, which is worse than either. The voice hooks would fire pointlessly on the Air. The autocompact hook would run mid-task on the Mini in the middle of an agent run. The settings would fight each other.

So I let them drift. ~/.claude/settings.json is a real file on each machine, not a symlink. The two diverged about a month ago and I haven't tried to re-converge them once.

#What sharing is actually for

The rule I settled on:

  • Share what's about what Claude should do. Tone, ethos, verification habits, scope discipline, deployment workflow, what to remember and what to forget. That stuff is mine, not the machine's. Symlink it.
  • Don't share what's about how Claude does it on this machine. Hooks, transcription, theme, which auto-approvals make sense given how I use this device. Leave that local.

Phrased another way: CLAUDE.md is the user manual. settings.json is the device driver. Sharing the manual makes sense. Sharing the driver does not.

#What I'd do differently

Two things I'd change if I were starting again:

  1. Put CLAUDE.md in the iCloud folder from day one, not in ~/.claude/. The symlink direction matters. If you ever delete the symlink by accident (or a Claude Code update touches ~/.claude/), you want the canonical file to be the iCloud one, not the linked one.
  2. Don't symlink anything stateful. Anything Claude Code itself writes (project memory, conversation history, MCP cache) needs to stay local. iCloud will fight you on file locking and rewrites in ways that aren't worth debugging. The first time I tried this I symlinked the whole ~/.claude/ directory and it broke within a day because the project-memory writes started racing iCloud sync. Two files, surgically chosen, is the move.

#The deliberate divergence

It feels weird at first to let two machines run different settings on purpose. The instinct is "they should be identical." But the machines aren't identical. The Air opens for short, focused sessions. The Mini runs unattended for hours at a time. The right hooks, auto-approvals, and skill set for those two contexts genuinely are different.

The shared part is the part that should be the same. Everything else can drift, and after a few months of running this setup I haven't tried to re-converge them once, which is the real test.

More from Blog