How to sync CLAUDE.md and Claude Code settings between machines

Claude Code does not sync your personal ~/.claude/CLAUDE.md or settings.json between computers. Keep one master copy in a git repository or a synced folder, then link or copy it into ~/.claude/ on every machine. Skills have a built-in route: upload one to your claude.ai account and it downloads into every terminal session signed in with that account, on Claude Code v2.1.273 or later.

Project files need nothing extra, because a CLAUDE.md committed to a repository arrives with git clone. The sections below list which personal files to move, the methods that work on macOS, Linux and Windows, and how a team shares instructions through a repository.

What to sync and what to leave behind

Paths are relative to ~/.claude/ unless they start with ~. On Windows, ~ means %USERPROFILE%. Anthropic’s .claude directory reference describes every file.

Path	What it holds	Sync it?
CLAUDE.md	Your instructions for every project	Yes
rules/	Personal rule files	Yes
skills/<name>/	Personal skills	Yes, one folder per skill
agents/, commands/	Personal subagents and older single-file commands	Yes
output-styles/, themes/, keybindings.json	Output styles, color themes, shortcuts	Yes
settings.json	Permissions, hooks, env, model, plugins and marketplaces	Yes, after the portability check below
Scripts your hooks or status line call	Whatever your settings point at	Yes, with settings.json
projects/<project>/memory/	Auto memory, notes Claude writes for itself	Through autoMemoryDirectory; see the FAQ
~/.claude.json	Sign-in session, trust decisions, user and local MCP servers	No
.credentials.json or the macOS Keychain entry	Your login	No. Run /login on each machine
projects/ transcripts, history.jsonl, file-history/, plans/	Session data in plaintext	No
sessions/, session-env/, shell-snapshots/, paste-cache/, debug/, backups/	Runtime state and caches	No
plugins/	Cloned marketplaces and plugin caches	No. Rebuilt from settings.json
skills/synced/	Skills downloaded from claude.ai	No. Claude Code overwrites it

Anthropic’s docs warn that anything passing through a tool lands in projects/<project>/<session>.jsonl in plaintext, including a .env file Claude once read. Syncing the whole ~/.claude folder copies those transcripts to every machine and every sync provider. The same applies to CLAUDE_CONFIG_DIR: it moves every ~/.claude path, credentials included, so pointing it at a synced folder syncs all of it.

MCP servers you added at user scope live in ~/.claude.json beside your OAuth session. Re-add them on each machine with claude mcp add --scope user, or bundle them in a personal plugin, covered below.

Codex, Gemini CLI, Copilot and OpenCode

Tool	Personal instructions	Settings	Skills	Never commit or sync
Claude Code	~/.claude/CLAUDE.md	~/.claude/settings.json	~/.claude/skills/	~/.claude.json, .credentials.json
Codex	~/.codex/AGENTS.md	~/.codex/config.toml	~/.agents/skills/	~/.codex/auth.json
Gemini CLI	~/.gemini/GEMINI.md	~/.gemini/settings.json	~/.gemini/skills/ or ~/.agents/skills/	~/.gemini/oauth_creds.json
GitHub Copilot CLI	~/.copilot/copilot-instructions.md
OpenCode	~/.config/opencode/AGENTS.md

Codex and Gemini CLI both read ~/.agents/skills/, so one synced folder serves the pair, while Claude Code needs each skill linked into ~/.claude/skills/. OpenCode falls back to ~/.claude/CLAUDE.md when its own file is missing. Sources: Codex AGENTS.md, Gemini CLI, Copilot CLI, OpenCode.

When you move to Claude Code from another agent, /import (v2.1.213 or later) copies that agent’s instruction files, MCP servers, commands, subagents and skills into Claude Code once.

Choosing a method

Method	Edits reach other machines	Windows
Git repository plus symlinks	When you commit, push and pull	Works, with the traps below
chezmoi	When you re-add, push and apply	Good, it copies files
GNU Stow	When you pull	macOS and Linux only
Syncthing or a cloud drive plus symlinks	Within seconds	Works, with the traps below
A synced notes vault, such as Jotura, plus symlinks	Within seconds	Works, with the traps below
claude.ai skills and plugins	Skills within minutes, plugins at the next start	Works
Your own plugin marketplace	On plugin update	Works

A dotfiles repository with symlinks

A dotfiles repository is a private git repository for your config. Move each file into it, then leave a symbolic link (a symlink) at the old path so Claude Code still finds it. On macOS and Linux:

mkdir -p ~/dotfiles/claude/skills ~/dotfiles/codex
mv ~/.claude/CLAUDE.md ~/.claude/rules ~/dotfiles/claude/
mv ~/.codex/AGENTS.md ~/dotfiles/codex/
for d in ~/.claude/skills/*/; do
  [ "$(basename "$d")" = synced ] || mv "$d" ~/dotfiles/claude/skills/
done

ln -s ~/dotfiles/claude/CLAUDE.md ~/.claude/CLAUDE.md
ln -s ~/dotfiles/claude/rules ~/.claude/rules
ln -s ~/dotfiles/codex/AGENTS.md ~/.codex/AGENTS.md
for d in ~/dotfiles/claude/skills/*/; do ln -sfn "${d%/}" ~/.claude/skills/; done

cd ~/dotfiles && git init -b main && git add . && git commit -m "Agent config"

Each skill gets its own link, and the move skips synced/, the folder where Claude Code puts skills from claude.ai. Linking the whole skills/ folder would send those downloads into your repository. Run git status before the first commit, since a token pasted into a skill’s helper script would go to the remote too.

On the second machine, move existing files aside before you link. ln -sfn cannot replace a real folder: it stops with “cannot overwrite directory” and Claude Code keeps reading the old copy. This version moves same-named skills to ~/.claude/skills-backup/, a folder Claude Code never reads:

git clone <your-remote> ~/dotfiles
mkdir -p ~/.claude/skills ~/.claude/skills-backup ~/.codex
mv ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak 2>/dev/null
mv ~/.claude/rules ~/.claude/rules.bak 2>/dev/null
mv ~/.codex/AGENTS.md ~/.codex/AGENTS.md.bak 2>/dev/null
ln -s ~/dotfiles/claude/CLAUDE.md ~/.claude/CLAUDE.md
ln -s ~/dotfiles/claude/rules ~/.claude/rules
ln -s ~/dotfiles/codex/AGENTS.md ~/.codex/AGENTS.md
for d in ~/dotfiles/claude/skills/*/; do
  n=$(basename "$d")
  if [ -d ~/.claude/skills/"$n" ] && [ ! -L ~/.claude/skills/"$n" ]; then
    mv ~/.claude/skills/"$n" ~/.claude/skills-backup/
  fi
  ln -sfn "${d%/}" ~/.claude/skills/
done

Claude’s Edit and Write tools refuse to write through a symlink and edit the link’s target, so its changes land in the repository copy. sed -i breaks a link by replacing it with an ordinary file, so check ls -l ~/.claude after a scripted edit. Claude Code also refuses to follow a CLAUDE.md or rules link that points at a network path such as \\server\share or /net.

chezmoi or GNU Stow

chezmoi copies files into place, so it needs no symlinks and behaves the same on Windows. chezmoi add ~/.claude/CLAUDE.md copies the file into ~/.local/share/chezmoi, and chezmoi init --apply <github-user> sets up a new machine in one command. An edit Claude makes to the live copy stays local until you run chezmoi re-add.

GNU Stow creates the symlinks for you from a package folder. Pass --no-folding: when ~/.claude does not exist yet, Stow links the whole directory to your package, and every transcript Claude Code writes lands in your repository. With --dotfiles, a package folder named dot-claude maps to ~/.claude.

Symlinks on Windows

Each row was checked on Windows 11 with Developer Mode on.

Shell	Command	Trap
Git Bash	ln -s target link	Copies the file by default. Set MSYS=winsymlinks:nativestrict for a real link
Command Prompt	mklink link target	Arguments run in the opposite order to ln -s. Folders need /D
Windows PowerShell 5.1	New-Item -ItemType SymbolicLink	Asks for administrator rights even with Developer Mode on
PowerShell 7	New-Item -ItemType SymbolicLink -Path link -Target target	Works without elevation once Developer Mode is on

A symlink needs Developer Mode or an elevated shell; search Windows Settings for “developer” to find the switch. In Git Bash, add export MSYS=winsymlinks:nativestrict to ~/.bashrc. Without it, ln -s silently writes a copy and your edits never reach the repository.

A directory junction needs neither Developer Mode nor admin rights, and works for folders such as rules\ or a skill:

cmd /c mklink /J "$env:USERPROFILE\.claude\rules" "$env:USERPROFILE\dotfiles\claude\rules"

Files still need a true symlink. With PowerShell 7 and Developer Mode on:

New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.claude\CLAUDE.md" -Target "$env:USERPROFILE\dotfiles\claude\CLAUDE.md"

Syncthing or a cloud folder

Put the real files in a folder that Syncthing, Dropbox, OneDrive or iCloud Drive mirrors, then run the git section’s link commands with that folder in place of ~/dotfiles. Edits arrive within seconds with no commit step. Each machine needs its own links, because a link exists only where you made it.

Cloud drives evict files you have not opened lately. iCloud Drive with Optimize Mac Storage and OneDrive with Files On-Demand leave a placeholder, and a skill can vanish with no error. Mark the folder “Keep downloaded” or “Always keep on this device”.

Simultaneous edits fork the file. Syncthing renames the older side to <name>.sync-conflict-<date>-<time>-<device>.md, and Dropbox and OneDrive write a conflicted copy. Claude reads files by name, so the conflict copy goes unread until you merge it by hand.

Dropbox, OneDrive and iCloud Drive store a copy on their servers, which Syncthing avoids by sending files between your own devices over encrypted connections.

Skills and plugins through Claude Code

Your claude.ai account is the first route. A skill you upload or enable in your claude.ai skill settings downloads into ~/.claude/skills/synced/ and also loads in Cowork and cloud sessions. Claude Code checks for changes about every 10 minutes while you work and every 40 while idle. Edit synced skills on claude.ai, because a later sync overwrites local changes.

Synced skills run with limits in the terminal. Claude Code does not run their ! command lines or attach the files their @ references name. The ${CLAUDE_PROJECT_DIR} and ${CLAUDE_SESSION_ID} placeholders reach Claude as literal text.

Plugins you turn on at claude.ai arrive as <name>@synced in a background sync after each start, and /reload-plugins loads them into a running session. Neither skills nor plugins sync when you sign in some other way. That covers an API key, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, apiKeyHelper and cloud providers such as Amazon Bedrock. Sync also stops under CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, --bare and --safe-mode.

A plugin marketplace you host is the second route. A marketplace is a git repository with a .claude-plugin/marketplace.json file listing plugins, and a plugin can bundle skills, subagents, hooks and MCP servers. That makes a private plugin a portable home for your MCP servers, with secrets kept in environment variables. Adding a marketplace writes it to extraKnownMarketplaces in your user settings.json, and installing a plugin writes it to enabledPlugins.

That turns settings.json into a reinstall list. On a new machine with the same file, Claude Code clones each declared marketplace in the background after startup and downloads the enabled plugins it lacks. Installing from your own marketplace takes two commands at the prompt, where claude-plugins is the name in its marketplace.json:

/plugin marketplace add your-github-user/claude-plugins
/plugin install my-tools@claude-plugins

Anthropic’s official marketplace is registered for you, so /plugin install commit-commands@claude-plugins-official works with no add step.

Keep settings.json portable

A permission rule for /Users/you/dev matches nothing on Windows, and a hook that calls a missing script fails on every session. Use ~/ paths where a setting accepts them and keep the scripts in the same repository. Claude Code also writes absolute paths for you: adding a marketplace from a local folder stores something like C:\Users\you\plugins, which does not exist on your Mac.

Claude Code writes through a symlinked settings.json and keeps the link. In a test with Claude Code 2.1.292, adding a marketplace updated the linked target. A text merge knows nothing about JSON syntax, so after edits on two machines, check the file still parses. Claude Code reports a broken file as a Settings Error at the next start.

Using a notes vault as the synced folder

A notes app that syncs a folder of Markdown files can hold your agent config, so you read and edit the instructions beside your other notes. Jotura works this way: a vault is an ordinary folder of .md files on your disk, and its optional sync carries the folder between your computers. It has no feature for agent files and syncs them like any other note, under these rules:

• Keep the real files in the vault and the links outside it. Jotura’s sync scans do not follow symlinks, so a link inside the vault never carries its target’s edits.
• Avoid dot-prefixed names. Sync skips anything starting with a dot, so a .claude folder in the vault never leaves the machine. Name it claude/.
• Check skill folders against the list of synced extensions. Files with no extension, files over 16 MiB and unlisted types stay behind. Anthropic’s docx, pptx and xlsx skills ship .xsd schema files, which never sync, and neither do .cjs, .mts, .lua or .php.
• Call hook scripts through their interpreter. Sync carries file contents only, so a script arrives without its execute bit. Write bash ~/Notes/agent-config/hooks/check.sh in settings.json.

A layout that works:

~/Notes/agent-config/
  AGENTS.md
  claude/CLAUDE.md
  claude/rules/
  claude/skills/<name>/SKILL.md

Link each piece once per machine with the git section’s commands, using ~/Notes/agent-config as the source. One AGENTS.md can serve as ~/.codex/AGENTS.md and ~/.gemini/GEMINI.md, and ~/.claude/CLAUDE.md can pull it in with an @~/Notes/agent-config/AGENTS.md line.

Jotura Sync is end-to-end encrypted, so the server never sees file contents or the paths inside your vault. It keeps three years of version history. When two machines edit the same note, a three-way merge writes one file and no conflict copy appears. Two edits to the same rule leave both lines in the file, this machine’s first, so read CLAUDE.md after editing it in two places.

The app is free and closed source. Sync costs £4 a month or £40 a year with no free trial; see the pricing page. Jotura can also share a folder with named people, though each of them needs a subscription too. A free git repository covers the same ground for anyone who wants reviewable diffs more than a notes app.

Sharing CLAUDE.md with your team

Commit the project files. Everything under the repository root reaches anyone who clones it, and changes go through pull requests. What belongs in the shared file is covered in what to put in CLAUDE.md.

Commit this	Gitignore this
CLAUDE.md or .claude/CLAUDE.md	CLAUDE.local.md
.claude/rules/, .claude/skills/, .claude/agents/	.claude/settings.local.json
.claude/settings.json (shared permissions, hooks, plugins)
.mcp.json, with ${API_KEY} placeholders for secrets

One file for every agent

Claude Code v2.1.277 and later reads a repository’s AGENTS.md directly when no CLAUDE.md exists. Once you add a CLAUDE.md, Claude reads that file alone, so make its first line an import:

@AGENTS.md

## Claude-specific
- Use the test-runner subagent for the full suite.

To have Claude read both files without the import, set Project instructions to claude-md-and-agents-md in /config. Anthropic advises against symlinking CLAUDE.md to AGENTS.md when anyone clones on Windows. Git checks a committed symlink out as a one-line text file unless core.symlinks is on.

Personal rules inside a shared repository

CLAUDE.local.md at the project root loads after CLAUDE.md and stays out of git, but it exists only in the worktree where you created it. It also counts as a CLAUDE.md, so adding one stops Claude reading the team’s AGENTS.md. An import from your home directory avoids both problems, and Claude Code asks once per project before loading it:

@~/dotfiles/claude/projects/acme-api.md

Where a committed file runs out

A committed file covers one repository, so rules for every repository get pasted into each one and drift apart. Personal skills never reach a teammate. Cloud sessions load the repository’s files and skip your home directory.

A team plugin marketplace covers the cross-repository layer. Declare it in the committed .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme/claude-plugins" }
    }
  },
  "enabledPlugins": {
    "acme-standards@acme-tools": true
  }
}

A teammate who accepts the workspace trust dialog gets the marketplace registered, and plugins stored inside the marketplace repository load from there. A plugin whose entry points at another repository needs claude plugin install acme-standards@acme-tools --scope project once per person, as Anthropic’s plugin install docs describe. Cloud sessions install neither.

On Claude for Teams or Enterprise, plugins an admin turns on under Organization settings > Plugins & skills on claude.ai reach every member as synced plugins. IT can also deploy a managed CLAUDE.md that loads for every user and cannot be excluded. It lives at /etc/claude-code/CLAUDE.md on Linux, with the macOS and Windows paths in the memory docs.

New laptop checklist

1. Install Claude Code and your other agents, and start each once so it creates its config folder.
2. Sign in with /login in Claude Code and the equivalent elsewhere. Never copy credential files.
3. On Windows, turn on Developer Mode, and set MSYS=winsymlinks:nativestrict in ~/.bashrc for Git Bash.
4. Clone your dotfiles repository, run chezmoi init --apply, or wait for the synced folder to finish downloading.
5. Move default files aside, then recreate every link. Links never sync.
6. Read settings.json for paths from the old machine before you use it.
7. Re-add MCP servers with claude mcp add --scope user.
8. Start a session, wait for the background plugin sync, run /reload-plugins, then check /plugin and /skills.
9. Ask Claude to summarize its standing instructions. A summary missing your rules points to a broken link or a wrong path.
10. Before you wipe the old machine, look for project CLAUDE.local.md files and auto memory you never copied.

Frequently asked questions

Does Claude Code sync CLAUDE.md between machines by itself?

No. Claude Code reads ~/.claude/CLAUDE.md from the machine it runs on and never uploads it. Only skills and plugins you enable on claude.ai sync through your account. Your instructions need a git repository, a synced folder or a tool such as chezmoi.

Can I sync the whole ~/.claude folder?

Syncing the whole folder causes problems. It holds plaintext transcripts that can contain secrets, credential files on Linux and Windows, caches with absolute paths, and runtime state that two running machines overwrite. Sync the files from the table and leave the rest local.

Does Claude Code’s auto memory sync?

No. Auto memory sits at ~/.claude/projects/<project>/memory/ on each machine. To carry it, set autoMemoryDirectory in the project’s .claude/settings.local.json on each machine to a folder inside your synced folder. Two machines working at once will both write MEMORY.md and produce sync conflicts, so notes your agent keeps on purpose travel better.

Will a symlinked CLAUDE.md work in Cowork and cloud sessions?

Terminal sessions follow the link. Cowork sessions skip a ~/.claude/CLAUDE.md that is a symlink or hard link, and skip user-file imports that point outside the session’s folder. Cloud sessions start from a fresh clone and never read your home directory, so commit the instructions or enable skills on claude.ai.