How to sync AGENTS.md across computers

There are two files called AGENTS.md, and only one of them syncs itself. A project AGENTS.md sits in a repository root and travels with git clone, so it already reaches every computer that has the repo. The personal one does not travel. It lives at ~/.codex/AGENTS.md, or %USERPROFILE%\.codex\AGENTS.md on Windows, and holds the preferences that belong to you rather than to any project.

To share that personal file between machines, pick one copy to be the original and write it out to every computer from there. Three approaches work. Keep it in a dotfiles git repository and link it into place. Put it in a folder your file-sync service already mirrors. Or keep it in a notes vault and run one command that writes it to the path each tool expects. This guide covers all three, then the conflict cases that bite once two computers edit at once.

The two AGENTS.md files

Knowing which file you want to share saves most of the work. Project instructions describe the repo: build commands, testing rules, conventions. Personal instructions describe you: how you like commits written, which tools to leave alone.

File	Where it lives	Applies to	Synced already?
Project AGENTS.md	repository root	work inside that repo	Yes, once committed
Nested AGENTS.md	any subdirectory	work under that directory	Yes, once committed
Personal AGENTS.md	~/.codex/AGENTS.md	every session on that machine	No

If your instructions are really about the project, commit them and stop reading. Everything below is about the personal file, which no version control system watches.

Option one: a dotfiles repository

Dotfiles are the hidden configuration files in your home directory, and plenty of people already keep them in git. If you do, this costs a minute. Move the real file into the repo and leave a symbolic link behind, a filesystem pointer that makes the old path keep working.

mkdir -p ~/dotfiles/codex
mv ~/.codex/AGENTS.md ~/dotfiles/codex/AGENTS.md
ln -s ~/dotfiles/codex/AGENTS.md ~/.codex/AGENTS.md
cd ~/dotfiles
git init && git add . && git commit -m "Add personal AGENTS.md"
git remote add origin <your-remote>
git push -u origin main

On the second computer, clone the repo and create the same link. Move any file already at the target path out of the way first, or the link fails with “File exists” and you risk losing instructions you wrote only there.

git clone <your-remote> ~/dotfiles
mkdir -p ~/.codex
mv ~/.codex/AGENTS.md ~/.codex/AGENTS.md.bak 2>/dev/null
ln -s ~/dotfiles/codex/AGENTS.md ~/.codex/AGENTS.md

The cost is that every edit needs a commit, a push, and a pull on the other side. Instructions you tweak mid-session tend not to get committed, so the machines drift. Windows is the weak spot. ln -s needs Developer Mode or an elevated shell, and in Git Bash it silently copies the file unless you set MSYS=winsymlinks:nativestrict. A copy is two independent files, which is the drift you were trying to prevent.

Option two: a folder your file-sync service already mirrors

Put the real file in Dropbox, iCloud Drive, OneDrive, or a Syncthing folder, then link it into ~/.codex/ on each machine exactly as above. Edits propagate without you doing anything, which fixes the main weakness of the dotfiles approach.

Two things are worth knowing before you trust it. The link is per-machine and never syncs itself, so you recreate it on every computer. And some clients hold the file open or write it back with a delay, so an agent can read a half-updated file mid-sync.

There is a privacy question too. Personal agent instructions describe your work in some detail, and on a mainstream cloud drive they sit in plaintext on someone else’s server. Syncthing avoids that by moving files straight between your own machines.

Option three: keep the original in your notes vault

If you already keep notes in plain markdown, the instructions can live there and be written outward. Jotura does this with its command-line tool. Your vault gets an Agents/ folder, one subfolder per agent tool, with the real filenames preserved:

Agents/
  Claude/CLAUDE.md
  Codex/AGENTS.md
  Codex/Skills/<name>/
  Gemini/GEMINI.md
  Copilot/copilot-instructions.md

The vault copy is the original and the files on disk are managed outputs. Check what has changed, preview the plan, then apply it:

jotura agents status
jotura agents sync --dry-run
jotura agents sync

What the first run does on a second computer depends on what is already there. If that machine has no ~/.codex/AGENTS.md, sync writes the vault copy into place and you are done. If it already has a different one, sync treats that as both sides changed: it reports a conflict, writes nothing for that file, and exits 16. You pick the winner yourself:

jotura agents sync --prefer vault    # the vault copy wins this run
jotura agents sync --prefer system   # the local file wins this run

Adoption runs the other way. Files the vault does not hold yet get pulled in from whichever machine has them, so building the vault in the first place never means retyping anything.

Be clear about what this costs. Nothing happens on its own: the system files only change when you run jotura agents sync on that machine, so this is one command per machine rather than zero. After the first sync, jotura context prints a drift line whenever the managed files have diverged, which is how an agent knows the command is due.

There is a price and a trust cost too. Jotura Sync is end-to-end encrypted and costs 4 pounds a month or 40 pounds a year, with no free trial. Jotura is closed source, so unlike a dotfiles repository you are trusting a binary with these files. What you can check is the output: the vault stays plain markdown, and Syncthing or a git repo can carry it instead if you would rather not pay.

When two computers edit the same instructions

Every approach has to do something here, and only one of them tells you it happened.

With a dotfiles repository, git reports the conflict at git pull and marks the file with standard conflict markers. You edit it, commit, and move on. That is the best outcome of the three, because nothing is lost and nothing is silent.

With a cloud sync folder, no client merges text and each one forks differently. Dropbox and OneDrive leave a second file beside the first, Syncthing writes a .sync-conflict- copy, and iCloud Drive may simply keep one side. No agent reads any of those files, and nothing tells you it happened.

With Jotura, sync writes nothing when both sides changed. It reports the conflict, skips that file, and leaves both copies alone, while every other file in the run completes normally. The run exits 16 so a script notices, and --prefer settles it. There is one more safety net: before the first apply overwrites a system file it has never recorded, sync copies the original to AGENTS.md.jotura-backup beside it.

Keep credentials out of it

Agent instruction files get shared, copied into repos, and pasted into issues. Treat AGENTS.md as public within your team. Put nothing secret in it: no API keys, no tokens, no internal hostnames you would not want quoted back at you.

Jotura enforces part of this. Sync only ever moves text files, and it refuses a fixed list of credential filenames, including auth.json, config.toml, settings.json, anything ending .pem, and anything starting id_rsa. Naming one in your own configuration does not override the block. Paths with a leading dot are skipped as well, files and folders alike, and binaries inside a synced folder are reported rather than copied.

A multi-machine setup is never symmetrical

Absolute paths are the usual reason a shared AGENTS.md misbehaves on the second computer. /Users/you/dev does not exist on Windows, and instructions that assume it produce confidently wrong behavior rather than an error. Write personal instructions in terms of the current repository, and keep anything genuinely machine-specific in a project file.

Missing tools are easier. If a computer has no ~/.codex directory because Codex is not installed there, jotura agents sync treats that tool as absent. Nothing applies, nothing errors, and status simply lists it, so one vault serves a machine with four agent tools and a machine with one.

FAQ

Do I need to do anything for project AGENTS.md? No. Commit it, and git pull is the whole sync mechanism. Only the personal file at ~/.codex/AGENTS.md needs help.

Should my personal instructions live in the project file instead? Only the parts a teammate would want too, such as build commands or testing rules. Everyone who clones the repo reads the project file, so anything about your own habits belongs in the personal one.

Does this cover Claude Code and Gemini as well? Yes, the same folder and the same command. Agents/Claude/CLAUDE.md maps to ~/.claude/CLAUDE.md and Agents/Gemini/GEMINI.md maps to ~/.gemini/GEMINI.md, with the same conflict rules for each. The Claude-specific walkthrough goes step by step.

What about skills, not just the instruction file? Skill folders run through the same engine, with extra rules about what gets skipped: dot-prefixed paths, binaries, and vendor-managed sets. Syncing agent skills across computers covers them.