Communicating settings from one Claude to another

The full network guide

This page (the hub) handles the config-sync question. Each sub-page handles a topic that needs its own real treatment — same depth, same design, all interconnected. Read in any order; they cross-reference each other.

The cost of drift

Every Claude session you have on an unconfigured machine costs you something. Every permission prompt is an interruption. Every "I don't have that MCP server here" is a workflow that doesn't run. Every custom slash command you set up on one machine and forgot on the others is muscle memory that fails three times before you remember why. The point of syncing isn't tidiness — it's keeping Claude usefully the same wherever you sit down.

What lives in ~/.claude/

On Windows that's C:\Users\<you>\.claude\; on macOS/Linux it's ~/.claude/. Below: every file and directory you're likely to find, what's in it, and — most importantly — whether you should sync it across machines.

The four config scopes

Claude reads config from multiple places and merges them. Knowing the precedence is what lets you sync the right thing at the right level.

Higher numbers lose to lower numbers — enterprise wins over CLI flags, CLI flags win over project-local, project-local wins over project-shared, project-shared wins over user-global. For multi-machine sync the actionable scope is 5 (user global). Everything else either propagates automatically (via git) or shouldn't propagate at all (per-invocation, machine-local).

Methods to sync, ranked

Five approaches, in roughly the order I'd recommend trying them. The right answer for most multi-machine setups is some combination of the first two.

The recommended setup for a multi-PC fleet

For a WholeTech-style setup — a handful of Windows PCs, the droplet, maybe a Mac in the mix — the sweet spot is git for declarations, sync folder for skills and memory, nothing for the rest. Concrete steps:

1. Pick a primary PC. The one you sit at most. This is where you author changes; the others receive them.
2. Initialise ~/.claude/ as a git repo. cd ~/.claude then git init. Create a private GitHub repo (e.g. walhus/claude-dotfiles) and add it as origin.
3. Write a .gitignore that excludes the noise. See the template below.
4. Commit the first snapshot. settings.json, CLAUDE.md, keybindings.json, commands/, agents/, skills/, output-styles/, statusline-config.json. Push.
5. On every other PC: back up the existing ~/.claude/, then git clone <repo> ~/.claude. Restore auth.json and any machine-specific bits from the backup, or re-run claude login.
6. For high-churn pieces (auto-memory, sometimes skills), symlink the subdirectory to a OneDrive/Dropbox folder so edits propagate without you having to remember to commit.
7. Cadence: after any meaningful settings change, git -C ~/.claude add && commit && push. Pull on the other machines first thing in the morning (or wire it into a scheduled task — see §14).

A working ~/.claude/.gitignore

# auth & secrets — never commit
auth.json
.credentials.json
*.env

# session state — machine-specific, large
sessions/
history.jsonl
shell-snapshots/
session-env/
file-history/
paste-cache/
tasks/
.claude.json

# caches
cache/
telemetry/
backups/
downloads/
mcp-needs-auth-cache.json

# per-project state, except memory (sync that explicitly if you want)
projects/*/history.jsonl
projects/*/sessions/
projects/*/cache/

# OS junk
.DS_Store
Thumbs.db
desktop.ini

settings.json — the file

The single most important file to sync. Every key it accepts, in plain English:

Older versions of Claude Code used mcp_servers (snake case) and a separate mcp.json file; current versions use mcpServers in settings.json. If both exist, the explicit settings.json wins. When you migrate, copy mcp.json into settings.json's mcpServers block and delete the standalone file.

A real ~/.claude/settings.json

This is a settings.json tuned for a WholeTech-style operator: multiple Windows PCs, an SSH droplet, MCP servers for Google + Slack, hooks for end-of-task notification, and an allowlist that takes the friction out of git/gh/ssh/scp/curl/rclone. Copy, then strip out anything you don't use.

{
  "theme": "dark",
  "model": "opus",
  "outputStyle": "default",
  "cleanupPeriodDays": 30,

  // === environment ===
  "env": {
    "DROPLET_HOST": "root@wholetech.com",
    "DROPLET_IP":   "143.198.182.180",
    "WEBSITES_ROOT": "C:\\Users\\walhu\\websites",
    "EDITOR":       "code --wait"
  },

  // === permissions ===
  // allow = run without asking; deny = block outright; ask = always confirm
  "permissions": {
    "allow": [
      // git essentials
      "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)",
      "Bash(git add:*)",    "Bash(git commit:*)", "Bash(git push:*)",
      "Bash(git pull:*)",   "Bash(git fetch:*)", "Bash(git branch:*)",
      "Bash(git checkout:*)", "Bash(git stash:*)",

      // GitHub CLI — read-only ops
      "Bash(gh pr view:*)", "Bash(gh pr list:*)", "Bash(gh pr diff:*)",
      "Bash(gh repo view:*)", "Bash(gh issue list:*)",
      "Bash(gh run list:*)", "Bash(gh run view:*)",

      // droplet ops — trust the host you control
      "Bash(ssh root@wholetech.com:*)",
      "Bash(ssh root@143.198.182.180:*)",
      "Bash(scp:*)",
      "Bash(rsync:*)",

      // dns + cert + http
      "Bash(nslookup:*)", "Bash(dig:*)", "Bash(curl.exe:*)",
      "Bash(certbot:*)",

      // package managers — read-only by default
      "Bash(npm ls:*)",      "Bash(npm view:*)",     "Bash(pnpm ls:*)",
      "Bash(npm run:*)",     "Bash(pnpm run:*)",    "Bash(yarn:*)",

      // backup + sync
      "Bash(rclone listremotes:*)", "Bash(rclone ls:*)",
      "Bash(rclone lsd:*)",         "Bash(rclone size:*)",

      // safe read tools
      "Read(*)", "Grep(*)", "Glob(*)", "WebFetch(*)"
    ],

    "deny": [
      // hard blocks — never run these without explicit confirmation
      "Bash(rm -rf /:*)",
      "Bash(rm -rf ~:*)",
      "Bash(git push --force:*)",
      "Bash(git push -f:*)",
      "Bash(git reset --hard:*)",
      "Bash(rclone delete:*)",
      "Bash(rclone purge:*)",
      "Bash(certbot delete:*)",
      "Bash(certbot revoke:*)"
    ],

    "ask": [
      // always confirm — risky but legitimate sometimes
      "Bash(npm publish:*)",
      "Bash(gh release:*)"
    ]
  },

  // === hooks ===
  // see §9 for full hook recipes
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "powershell -c \"[console]::Beep(880,200)\"" }]
    }]
  },

  // === mcp servers ===
  // each entry is the launch command for an MCP server. Secrets via env, not hardcoded.
  "mcpServers": {
    "filesystem-websites": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\walhu\\websites"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GH_PAT}" }
    }
  },

  "statusLine": {
    "format": "{cwd} · {model} · {branch} · {tokens}"
  }
}

Allowlist patterns worth standardising

Permissions are the single biggest friction reducer. Every tool/command pair that appears in your day-to-day belongs on the allowlist; every command that's destructive belongs on the deny list. Below: the patterns that pay back in any multi-PC fleet.

Syntax cheatsheet

• "Read(*)" — allow Read on anything. (Almost always safe.)
• "Bash(git status:*)" — allow git status with any args.
• "Bash(ssh root@wholetech.com:*)" — allow ssh to that specific host with any args.
• "Bash(rm -rf /:*)" — match an exact destructive pattern.
• "Bash(curl http*)" — match a prefix.

Patterns match against the full command line. Use :* as the trailing wildcard if you want to allow any arguments. Lists are matched most-specific-deny-wins → allow → ask.

Three tiers, in priority order

The allowlist that earns its keep on Paul-shaped work

// version control — every read, write to your own remotes
"Bash(git *:*)",          // allow everything in git — narrower if you prefer
"Bash(gh pr view:*)",      "Bash(gh pr list:*)",     "Bash(gh pr diff:*)",
"Bash(gh run view:*)",     "Bash(gh run list:*)",    "Bash(gh repo view:*)",

// SSH to hosts you control (be specific — don't whitelist ssh:*)
"Bash(ssh root@wholetech.com:*)",
"Bash(ssh root@143.198.182.180:*)",
"Bash(scp:*)",

// HTTP probes & DNS
"Bash(curl.exe -s*)",      "Bash(curl.exe -sI*)",     "Bash(curl.exe -X GET*)",
"Bash(nslookup:*)",        "Bash(dig:*)",            "Bash(host:*)",

// rclone — read-only verbs
"Bash(rclone ls:*)",       "Bash(rclone lsd:*)",      "Bash(rclone size:*)",
"Bash(rclone listremotes:*)", "Bash(rclone check:*)",

// safe Claude built-ins
"Read(*)", "Grep(*)", "Glob(*)", "WebFetch(*)", "WebSearch(*)"

Use /fewer-permission-prompts to audit

The bundled skill fewer-permission-prompts scans your transcripts, ranks common read-only commands by frequency, and proposes an allowlist for the project's .claude/settings.json. Run it on the primary PC, copy the suggestions up to ~/.claude/settings.json if they're broadly applicable, and commit.

Hooks worth setting once

A hook is a shell command Claude runs automatically when something happens. Lifecycle events available: UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStop, Notification, SessionStart. Three I'd recommend across every machine:

1. Beep when Claude stops

The single highest-value hook: an audible cue that Claude finished. Lets you walk away during long runs without watching the screen.

"hooks": {
  "Stop": [{
    "matcher": "",
    "hooks": [{
      "type": "command",
      // Windows: PowerShell beep. macOS: 'afplay /System/Library/Sounds/Glass.aiff'. Linux: 'paplay /usr/share/sounds/freedesktop/stereo/complete.oga'
      "command": "powershell -c \"[console]::Beep(880,200)\""
    }]
  }]
}

2. Push notification on long jobs

Pair the beep with a Pushover / ntfy / Slack message so you get notified on your phone. Especially useful when Claude is running a background agent or a cloud task.

"Stop": [{
  "matcher": "",
  "hooks": [{
    "type": "command",
    "command": "curl.exe -s -d \"Claude finished\" ntfy.sh/walhus-claude"
  }]
}]

3. Auto-format after every Edit/Write

Run Prettier/Black/gofmt automatically on files Claude touched. Keeps the diff clean and saves you from "Claude wrote it with the wrong quote style" comments in code review.

"PostToolUse": [{
  "matcher": "Edit|Write|MultiEdit",
  "hooks": [{
    "type": "command",
    // CLAUDE_FILE_PATHS is set by the harness; format only what was touched
    "command": "for f in $CLAUDE_FILE_PATHS; do npx prettier --write \\\"$f\\\" 2>/dev/null || true; done"
  }]
}]

4. Guard against committing to main

A pre-tool gate that intercepts git push to main/master and forces a confirmation.

"PreToolUse": [{
  "matcher": "Bash",
  "hooks": [{
    "type": "command",
    // returns nonzero (= block) if pushing to main
    "command": "powershell -c \"if ($env:CLAUDE_TOOL_INPUT -match 'git push.*\\bmain\\b') { Write-Host 'Refusing to push main — confirm in chat'; exit 2 }\""
  }]
}]

MCP servers across machines

MCP servers are how Claude reaches outside its sandbox — Gmail, Calendar, Drive, Slack, your own filesystem trees, GitHub, Postgres. The declaration is portable; the auth is not. Sync the declarations, re-auth per machine.

What to put in settings.json

"mcpServers": {
  "filesystem-websites": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\walhu\\websites"]
  },
  "filesystem-secrets": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\walhu\\.secrets"]
  },
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GH_PAT}" }
  },
  "postgres-walhus": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres", "${env:WALHUS_DB_URL}"]
  }
}

Auth lives outside the synced file

The Google MCP servers (Gmail, Calendar, Drive) and Slack auth via OAuth on first use. The browser flow writes a token into ~/.claude/mcp-needs-auth-cache.json and a per-server token file. Don't sync those. Each machine does its own one-time auth.

The pattern Paul already uses

The Google + Slack MCP servers in this fleet (Gmail, Calendar, Drive, Slack — see /integrations) authenticate via claude.ai and don't appear in mcpServers at all — they're managed connectors. The ones that DO live in mcpServers are the local ones: filesystem trees you've granted access to, your GitHub server, your Postgres pointer.

Practical rule: add a new MCP server on the primary PC; commit the settings.json change; pull on the others; let each one do its own auth dance.

Skills, agents, commands, plugins

These four are folders of declarations rather than fields in settings.json, so the sync story is even simpler: copy the folder, restart Claude.

Two skills worth carrying everywhere

• /session-close — appends a session summary to sessions.wholetech.com. If you use it on one machine, sync the skill so the rolling log keeps growing wherever you happen to be working.
• /fewer-permission-prompts — built-in skill that proposes allowlist entries from your transcripts. Useful on a fresh machine to bootstrap an allowlist without typing every rule.

The 'plugin' shortcut for distributing your own stuff

If you find yourself maintaining the same five custom commands across machines, bundle them as a plugin and publish it (private repo is fine). Then every machine runs /plugin install <repo> and gets the same set. Updates propagate by running install again. Heavier than git-syncing the commands/ folder, but cleaner if you ever want to share the bundle with someone else.

Auto-memory — sync, or keep local?

Auto-memory is the file-based memory system at ~/.claude/projects/<project-slug>/memory/. Each memory file is a markdown card with frontmatter; MEMORY.md is the index. This is where Claude remembers who you are, what you're like to work with, and what you've already corrected it on. It's the highest-leverage thing you could sync — and the most context-sensitive.

What's in there (a real example)

The auto-memory for the C--Users-walhu-websites project on this machine currently holds, indexed in MEMORY.md:

• feedback_brisk_replies.md — "user gives one-word answers; act, don't re-prompt with multi-question blocks"
• user_personal_context.md — "Austin TX, married, also operates rental properties; OfficeHours.global participant"
• reference_deploy_wholetech_subdomain.md — the GoDaddy → droplet → certbot runbook for *.wholetech.com
• feedback_content_rules_public_sites.md — "no Claude/Anthropic naming on new public sites without checking; no Paul's real name; institutional bylines"
• feedback_no_browser_scanners_on_droplet.md — "Playwright/Lighthouse crash the droplet (2026-04-28); run from a Windows PC against it instead"
• feedback_dont_phone_it_in.md — the standing rule: never phone in content; match the depth of surrounding work

That last one is the case for syncing. The rule was established on one machine in one conversation; if it doesn't propagate to the others, Claude on the other machines will phone things in until you re-correct.

The case against syncing

Memory is context-specific. A memory written while configuring a Mac may not apply on Windows. A memory about a specific project's quirks doesn't help another project. And memories that capture in-flight conversation state (rare, but it happens) can mislead.

The compromise that works

Sync the memory directory structure via a symlink/junction to a OneDrive folder, so memories propagate live, but treat the memory index as authoritative and prune aggressively:

1. Move the memory folder out of ~/.claude/projects/<slug>/ into a sync-able location: ~/OneDrive/claude-memory/<slug>/.
2. Replace the original folder with a symlink/junction. On Windows: mklink /J "C:\Users\walhu\.claude\projects\<slug>\memory" "C:\Users\walhu\OneDrive\claude-memory\<slug>". On macOS/Linux: ln -s ~/OneDrive/claude-memory/<slug> ~/.claude/projects/<slug>/memory.
3. Repeat the symlink on every machine — same target, same source. OneDrive does the heavy lifting.
4. Review MEMORY.md weekly. Prune stale entries. Memories decay; the index is your hygiene tool.

What goes wrong

Setting up a new machine

The whole point of doing the sync work is that a new machine is fast. Below: the steps to go from a blank Windows install to a fully-configured Claude in about ten minutes. Adapt freely.

1. Install Claude Code. npm install -g @anthropic-ai/claude-code (or the equivalent from /newby/).
2. Authenticate. claude once, sign in via the browser. This creates ~/.claude/ with the auth files but nothing else.
3. Move that ~/.claude/ aside. mv ~/.claude ~/.claude.bak (or rename in Explorer). Keeps a safety net.
4. Clone the dotfiles repo. git clone git@github.com:<you>/claude-dotfiles ~/.claude.
5. Restore the auth bits. Copy auth.json from ~/.claude.bak back into ~/.claude — or just re-run claude login.
6. Symlink the memory folder to OneDrive (or wherever your shared memory lives). See §12.
7. Set the machine-local secrets. Drop ~/.secrets/godaddy.env, ~/.secrets/rclone.conf, or whatever per-PC creds you keep out of git.
8. Open a session. Confirm: theme is right, status line looks right, an allowlisted command runs without prompting, an MCP server is listed, /your-custom-command works.

A scheduled task to keep dotfiles fresh

On Windows, a daily morning task that git -C ~/.claude pull --ff-only means you arrive at work and the latest settings are already there. Same idea as the CC-Mirror-* tasks on the WholeTech fleet.

# Windows Task Scheduler one-liner — registers a daily 09:00 pull
schtasks /create /tn "Claude dotfiles pull" /tr "git -C C:\Users\walhu\.claude pull --ff-only" /sc daily /st 09:00

For the WholeTech fleet specifically

Drop the dotfiles repo into the same 6-leg backup pattern you already run — droplet, B2, GitHub, Drive, HS NAS, CC NAS. Then losing a PC doesn't lose your Claude config; even the secrets you carefully kept out of the repo are independently backed up via your existing scheduled tasks.

See also