---
title: "One instruction file for every coding agent – Olli Junes"
url: https://ollijunes.com/agents-md-sync-one-instruction-file-for-every-coding-agent/
description: "Claude Code, Codex and Gemini CLI each read their own instruction file. agents-md-sync copies one source to all of them and catches a copy that was edited."
language: en
alternate_fi: https://ollijunes.com/fi/agents-md-sync-yksi-ohjetiedosto-kaikille-koodausagenteille/index.md
index: https://ollijunes.com/llms.txt
---

Nov 19, 2026[AI & Growth](https://ollijunes.com/category/ai-growth/) 4 min read

# Three coding agents, three copies of my rules. I wrote a tool that keeps one.

Claude Code, Codex and Gemini CLI each read their own instruction file. agents-md-sync copies one source to all of them and catches a copy that was edited.

[Lue suomeksi](https://ollijunes.com/fi/agents-md-sync-yksi-ohjetiedosto-kaikille-koodausagenteille/)

![agents-md-sync: one instruction file for every coding agent, and a warning when a copy drifts. Claude Code, Codex, Gemini CLI.](https://ollijunes.com/_emdash/api/media/file/01M7TB09P305D0Q3T47MAY36CV.png)

I use more than one coding agent. Each of them reads its instructions from its own file. Claude Code wants `~/.claude/CLAUDE.md`. Codex wants `~/.codex/AGENTS.md`. Gemini CLI wants `~/.gemini/GEMINI.md`. The text in them should be the same, because they are my rules, not the tool's.

Kept by hand, they do not stay the same. You fix a rule in one file and forget the others. Agents also write to these files themselves, so a copy can change without you touching it. So I wrote [agents-md-sync](https://github.com/ollijunes/agents-md-sync).

## The problem

Three files with the same content are three chances to be wrong. Nothing tells you when they differ. The agent that reads the old copy does not know it is old. It follows it.

A symlink solves part of this. It stops working the day a tool or a sync service replaces the link with a regular file, and nothing tells you that either.

## What agents-md-sync does

You pick one file and edit only that. `publish` copies it to the place each tool reads. `check` compares the copies with the source.

The tool remembers what it wrote. That lets it tell two cases apart. A copy that still matches the last publish is stale: the source moved on, and `publish` updates it. A copy that matches neither the source nor the last publish was edited by someone, and `publish` stops. It writes nothing, not even to the other tools, until you have looked.

`diff` shows what changed in the edited copy. You move the lines you want into the source and publish again. If you want none of them, `--force` overwrites the copy and keeps the old one in a backup folder.

`check --quiet` prints nothing when all is well and exits with an error code when a copy differs. That makes it a one-line session hook or cron job.

The same tool works inside a repository. A small config file names `AGENTS.md` as the source and `CLAUDE.md` and `GEMINI.md` as copies, and `check` in CI fails when they differ.

## Safety

The copies are written to a temporary file and renamed into place, so an agent never reads half a file. The tool refuses a source that is empty, cut off or larger than 32 KiB, the size at which Codex stops reading by default. It never writes through a symlink.

A config file found in a repository is confined to that repository. It can only use relative paths inside its own folder. Running `publish` in a project you cloned cannot replace the instruction file in your home folder. A security review of the first version found exactly that hole, and the fix has its own tests.

## What I have tested

The tests build a home folder in a temporary directory and never read the real one. They cover a first publish, a stale copy, an edited copy, a forced overwrite with its backup, symlinks, a failed write, and eight ways a repository config could try to reach outside its folder. CI runs them on Linux and macOS with Python 3.11 to 3.14.

I have run the whole flow by hand against a synthetic home folder. The examples in the README are that output.

I have used the same idea as a short shell script on my own machines. This tool is a rewrite of it with the checks the script did not have. I have not yet moved my own setup to it.

## What it does not do

The copies are identical. There is no section for one tool only and no conversion between formats. If one agent needs different rules, use something else. It does not merge an edited copy for you. It has built-in locations for four tools; any other tool is a path you add yourself. Windows is untested.

## Try it

The code is at [github.com/ollijunes/agents-md-sync](https://github.com/ollijunes/agents-md-sync). Run `init` with the file you want to edit, then `check`, then `publish`. If a tool already has an instruction file, the first publish stops and shows you. That is on purpose.

Issues and pull requests are welcome. Please describe problems with synthetic files, not with your own instructions.

[![Olli Junes](https://ollijunes.com/wp-content/themes/ollijunes-theme/assets/img/olli-junes.webp)](https://gravatar.com/resacolli)

[Olli Junes](https://ollijunes.com/story/)

Olli Junes is the founder and CEO of Resaco, Resappi and ResaHost, based in Rovaniemi, Finland. An entrepreneur since 2007, his background spans photography, sales and sales leadership in Finland and Sweden. He writes about entrepreneurship, sales and RevOps.

Olli elsewhere: [Resaco Finland](https://resaco.fi/olli-junes/) · [Resaco International](https://resaco.co/olli-junes/) · [ResaHost](https://resahost.net/tiimi/olli-junes/) · [Yrittäjäopas](https://yrittajaopas.com/kirjoittajat/olli-junes/)

[LinkedIn](https://www.linkedin.com/in/ollijunes/) [GitHub](https://github.com/ollijunes) [Gravatar](https://gravatar.com/resacolli) [X](https://x.com/resacolli) [Instagram](https://www.instagram.com/ollijunes/) [Threads](https://www.threads.net/@resacolli)

[ PreviousI pull other people's repositories without reading them. So I wrote a tool that reads first.](https://ollijunes.com/upstream-watch-git-clones-before-you-pull/)

[ Back to blog](https://ollijunes.com/blog/)
