How to sync CLAUDE.md between machines

A CLAUDE.md file is ordinary text on disk. Syncing it between machines is a file-sync problem, not a Claude Code problem.

You have three sensible options. Commit the file to a git repository and pull it on the other machine. Put it inside a file-sync service like Syncthing or Dropbox. Or keep the canonical copy in a notes vault and run a command that writes it out on each machine.

If you have no strong preference, use the git repository. It is free, you already know the tools, and the rest of this page explains when the other two earn their keep.

Which option suits you depends on which CLAUDE.md is drifting. Project files sit at the root of a repository and are already solved: commit, push, pull on the other machine. The file that actually drifts is the global one at ~/.claude/CLAUDE.md on macOS and Linux, or %USERPROFILE%\.claude\CLAUDE.md on Windows.

That path sits outside every repository, so nothing carries it anywhere unless you set that up on purpose. The same goes for the skills in ~/.claude/skills/.

Work out what you are actually syncing

Before picking a method, list the files. Claude Code reads instructions from a small, knowable set of places, and each one has a different natural home.

File	Location	Best home
Project instructions	CLAUDE.md at the repo root	The repo itself, committed
Global instructions	~/.claude/CLAUDE.md	A dotfiles repo or a synced vault
Skills	~/.claude/skills/<name>/SKILL.md	A dotfiles repo or a synced vault
Machine-specific rules	A file imported from CLAUDE.md	Stays put, never shared
Settings	~/.claude/settings.json	Move by hand, with care

If you only care about project instructions, stop reading and commit them. Everything below is about the global layer, which is where Claude Code config sync gets interesting.

Option one: a git dotfiles repository

A dotfiles repository is a git repo holding your personal config files. Create one, move the global file into it, then replace the real path with a symbolic link, or symlink, pointing at the copy in the repo. On a new machine you clone the repo and re-create the link.

mkdir -p ~/dotfiles/claude
mv ~/.claude/CLAUDE.md ~/dotfiles/claude/CLAUDE.md
ln -s ~/dotfiles/claude/CLAUDE.md ~/.claude/CLAUDE.md
cd ~/dotfiles && git add . && git commit -m "Track global CLAUDE.md"

The strengths are real: full history, line-level diffs, blame, and merge tooling you already understand. When both machines change the file you get a merge conflict, which is loud and which you know how to resolve.

The weakness is that it updates only when you remember to commit and pull. Instructions you refine mid-session on your laptop stay on your laptop until you push them. Windows makes symlinks awkward enough that many people script a copy step instead.

Option two: general file sync

Putting the files inside Syncthing, Dropbox, iCloud Drive, or OneDrive removes the remembering step. Changes propagate on their own, usually within a few minutes, though how promptly depends on the service.

Two cautions, and both bite. First, these tools sync whatever is in the folder, including the caches, logs, and session state that Claude Code writes constantly. Sync the specific files you care about rather than the whole .claude directory.

Second, only Syncthing keeps real bytes on every machine as a matter of course. Dropbox, iCloud Drive, and OneDrive can evict a file to the cloud and leave a placeholder behind, and a tool reading that path then gets a stub or a stall. If you use one of those, turn off its online-only or optimize-storage setting for this folder.

The conflict story is the weakest part. Two machines writing at once leaves a dated conflicted copy beside the original. Claude Code only reads CLAUDE.md by name, so it never sees that copy. Your newer edits sit in a file nothing loads, and nothing warns you.

Option three: keep the config in a synced notes vault

The third approach treats agent instructions as content rather than as dotfiles. The canonical copy lives in a notes vault, and a command reconciles it with each tool’s expected location on the machine you are sitting at. It suits instructions that read more like a document than like code.

Jotura works this way, and it is closed source. If running only auditable code over your agent config matters to you, the dotfiles repository is the honest answer and you can stop here.

The vault is an ordinary folder of Markdown files. An Agents/ folder inside it holds a subfolder per tool: Agents/Claude/CLAUDE.md, Agents/Codex/AGENTS.md, Agents/Gemini/GEMINI.md, and Agents/Copilot/copilot-instructions.md. Each tool keeps its own file. You get one synced place to edit all of them and one command to install them, not one file that serves every tool.

jotura agents status              # read-only drift report, changes nothing
jotura agents sync --dry-run      # show what a real run would do, change nothing
jotura agents sync                # reconcile the vault with each tool

jotura agents sync runs in both directions. It writes vault edits out to ~/.claude, and it pulls edits you made directly in ~/.claude back into the vault.

It moves text files only, and it names every dot-prefixed path or binary file it skips. It also refuses to touch settings.json, auth.json, credentials.json, .pem files, and anything starting id_rsa. Credentials stay where they are, and settings stay yours to move.

When both copies of a file changed since the last sync, agents sync skips that file rather than picking a winner, and the run exits with code 16. You resolve by naming the side that wins:

jotura agents sync --prefer vault
jotura agents sync --prefer system

That flag applies to every conflicted file in the run, not one at a time. To split the decision across files, copy the losing content out by hand first, then run it.

The dotfiles repository still wins where you want line-level diffs and blame, or where the machine is a headless server or a container that cannot run a desktop app.

Getting the vault onto the second machine

A vault is a plain folder, so any transport moves it. Syncthing or a git repository moves one for free.

The paid option is Jotura Sync at £4 per month or £40 per year, with no free trial. Your device derives the keys, each file gets its own key, and each file path becomes a keyed hash, so the server stores your notes without ever seeing your plaintext, your filenames, or your keys. Recovery runs through a BIP39 phrase you hold, the same word-list standard cryptocurrency wallets use.

Concurrent edits from two machines merge automatically instead of leaving conflicted copies. There is no iOS app, so a Mac, Windows, Linux, or Android machine can take part and an iPhone cannot.

Write instructions that survive the crossing

Syncing the file is the easy half. Making one file correct on two machines takes a little discipline.

Absolute paths are the usual culprit. A line naming /Users/you/dev/project is wrong the moment it lands on a Windows box, and an agent will follow it into a dead end. Prefer paths relative to the repository, or describe the location in words.

Do the same with anything else that differs between machines: shell names, package managers, GPU availability, and local port numbers. If a rule applies to one machine only, keep it in a separate file and pull it in with an import line in CLAUDE.md. Claude Code prefers that import syntax to the older CLAUDE.local.md, which misbehaves across git worktrees.

Frequently asked questions

Does Claude Code sync CLAUDE.md itself? No. Claude Code reads the file from disk on the machine it is running on. Getting it there is your job.

How do I share CLAUDE.md across computers running different operating systems? All three methods work across macOS, Windows, and Linux. The content is the harder half: keep absolute paths and shell-specific commands out of the shared file.

Can I mix approaches? Yes, and most people do. Project instructions live in each repository, while the global file and skills travel by one of the methods above.

Will syncing settings.json break anything? It can, if the file records machine-specific paths or permissions you granted on one machine only. Move it by hand, after your instructions are working.

Related reading

• Setting up agent config on a new laptop
• Sync agent skills across computers
• Sync AGENTS.md across computers
• The jotura command-line tool
• Sync pricing