One AGENTS.md for Claude Code, Codex and OpenCode

Three agents, three instruction files, and only one of them gets updated. Here is the small setup that keeps Claude Code, Codex and OpenCode on the same rules — and on the same decisions.

Published: October 2026 Reading time: 6 min Topic: Agent Memory

The problem: each agent reads a different file

Codex and OpenCode look for AGENTS.md in the project root. Claude Code looks for CLAUDE.md. So the same rule — run the tests before you commit, do not touch the migrations — has to be written twice. After a few weeks the two copies disagree. The agent you did not update follows the old rule, and you spend the review looking for the difference instead of looking at the code. Copying the file does not fix it either: two copies drift again the first time someone edits one. What you want is one file with one owner, and a pointer from the other agent's file.

One AGENTS.md, imported by CLAUDE.md

Put the content in AGENTS.md. Then create CLAUDE.md with a single line: @AGENTS.md. Claude Code supports @path imports, so it reads the same file at the start of the session. Codex and OpenCode read it directly, with no extra step. That is the whole file. Commit both: a rule that lives only on your machine is invisible to a teammate, to a worktree and to a fresh clone. If you later need a Claude-specific note, put it below the import line; do not start a second copy of the shared rules, because that copy is the one that goes stale.

What goes in the file

Short beats complete. The file is read at the start of every session, so every line spends context before any work begins. Four parts are usually enough:

Project summary. What the repo does, the main folders and the stack. Three or four lines, not a design document.
Commands. Install, dev, build, test, lint. The exact commands, because an agent that has to guess will guess wrong.
Rules. What must not happen: do not edit the migrations, ask before adding a dependency, keep the public API stable.
Decisions. Dated lines that explain a choice, so the next session does not reopen a question you already settled.

A short example, with the commands replaced by the ones your project actually uses. The commands are copy-pasteable and the rules are negative on purpose: "write clean code" gets ignored, "do not edit files in db/migrations" does not.

# Project
A small web app: TypeScript API, React front end, Postgres.
API code in src/api, UI in src/web, migrations in db/migrations.

## Commands
- Install: npm install
- Dev: npm run dev
- Test: npm test
- Build: npm run build

## Rules
- Run npm test before you call a task done.
- Do not edit files in db/migrations; add a new migration instead.

## Decisions
- 2026-10-14: Postgres stays; reports use the same database.

The end-of-session habit

A file like this stays true only if something writes to it. At the end of a session, before you close the terminal, say: "Add today's decisions to AGENTS.md." Then read the diff of that file the way you read code. Look for a decision you did not make, a rule that contradicts an older line, or a paragraph that describes a file that no longer exists.

Keep it to rules and decisions, not a diary. If a line has been wrong for a month, delete it in the same commit. Stale instructions are worse than missing ones, because the agent follows them confidently. The same habit covers compaction: when a long conversation is summarized, details can be lost, but a decision written to AGENTS.md survives the summary, the session and the switch to another agent.

How Foxpit keeps one memory

Foxpit is a desktop app that runs Claude Code, Codex, OpenCode and Antigravity as one team, and every agent on a project shares one project memory. It lives in .foxpit/memory inside your repo as plain markdown with [[links]], with a notes view and a graph. A new session on any agent already knows yesterday's decisions, files and open threads.

One memory, every agent. Claude Code, Codex, OpenCode and the built-in engine read the same project memory, so a rule is written once.
It sits in the repo. Plain markdown next to your code, so it appears in a diff and travels with a clone.
Notes view and graph. You can read the memory the way the agent does, instead of guessing what it remembered.

Foxpit

Related: Shared memory for AI coding agents covers the wider picture, and Claude Code + OpenCode shows how to hand a task from one agent to the other.

Frequently asked questions

Do I need both AGENTS.md and CLAUDE.md?

You need AGENTS.md for Codex and OpenCode. For Claude Code, add a CLAUDE.md with one line, @AGENTS.md, so it imports the same file. Keep the shared rules in AGENTS.md only.

Where should AGENTS.md live?

In the project root, next to the code it describes. Agents look for it there, and it stays with the repository when you clone it or open a worktree.

How long should the file be?

As short as it can be and still answer four questions: what is this project, how do I run it, what must I not do, and what has already been decided. A page is usually enough, because every line is read in every session.

Does a written decision survive a long session?

A summary can drop details, but a file on disk does not. A decision written to AGENTS.md is still there after compaction, in a new session, and after you switch to another agent.

One file, three agents, the same rules.

Download Foxpit Shared Agent Memory