AGENTS.md vs CLAUDE.md: one instruction file for every agent.
Claude Code reads CLAUDE.md and falls back to AGENTS.md, while Codex, OpenCode and many other agents read AGENTS.md. Keep your instructions in one AGENTS.md, point Claude Code at it when you need to, and keep it short enough for each session to carry.
Two files for the same job
An instruction file is a Markdown file in your repository that a coding agent reads when a session starts. It holds your build and test commands, your code style and the project's rules. Claude Code's file is CLAUDE.md. AGENTS.md is an open format that the Agentic AI Foundation, part of the Linux Foundation, stewards, and agents.md lists Codex, Cursor, Gemini CLI, GitHub Copilot and opencode among the tools that use it.
Neither file has required fields. Write plain Markdown under whatever headings suit you.
Which agents read which file
Four agents as examples, with the file each reads in your repository and the personal file it reads for all your projects:
| Agent | In the repository | For all your projects |
|---|---|---|
| Claude Code | CLAUDE.md or .claude/CLAUDE.md; AGENTS.md when there's no CLAUDE.md | ~/.claude/CLAUDE.md |
| Codex | AGENTS.override.md, else AGENTS.md | ~/.codex/AGENTS.override.md, else ~/.codex/AGENTS.md |
| OpenCode | AGENTS.md, else CLAUDE.md | ~/.config/opencode/AGENTS.md, else ~/.claude/CLAUDE.md |
| Gemini CLI | GEMINI.md, or the names you set in context.fileName | ~/.gemini/GEMINI.md |
Sources: the docs for Claude Code, Codex, OpenCode and Gemini CLI. Check your own agent's docs for the names it reads.
Keep your instructions in AGENTS.md
Write the project's instructions once, in an AGENTS.md at the repository root, and commit it. Codex and OpenCode read it with no setup. Claude Code reads it from v2.1.277, as long as no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in your working directory or a directory above it. Your personal ~/.claude/CLAUDE.md doesn't count, and loads alongside. Once Claude Code picks up the file, the conversation shows a line like this:
no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.mdA CLAUDE.local.md counts as a CLAUDE.md, so adding one for your personal notes stops Claude Code reading AGENTS.md. To keep both, type /config and set Project instructions to claude-md-and-agents-md.
Gemini CLI reads GEMINI.md until you tell it otherwise. Add the file names to .gemini/settings.json in the repository:
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}Import AGENTS.md into CLAUDE.md
Keep a CLAUDE.md when you have instructions for Claude Code alone, or when a session can't read AGENTS.md itself: a Claude Code release before v2.1.277, or one with the built-in plugin that reads it turned off. Start the file with an import. This example comes from Claude Code's memory docs:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.Claude Code expands @AGENTS.md in place, so Claude reads the shared file first and your Claude notes after it. The path resolves from the file that holds the import, and an imported file can import others, up to four hops deep. Claude Code doesn't load AGENTS.md twice, even when you've told it to read both files.
A sentence can't stand in for the import. If your CLAUDE.md says "See AGENTS.md", Claude sees AGENTS.md only if it decides to open the file. Write the import, or delete the CLAUDE.md and let Claude Code read AGENTS.md on its own.
Or symlink CLAUDE.md to AGENTS.md
If you have nothing to say to Claude Code alone, a symlink keeps one file on disk:
$ ln -s AGENTS.md CLAUDE.mdClaude Code's docs list two limits:
- Claude's Edit and Write tools refuse to write through the link, and send Claude to edit
AGENTS.mdinstead. - On Windows, a symlink needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a plain text file unless
core.symlinksis on. That clone gets a one-lineCLAUDE.mdin place of your instructions. If anyone on your team works on Windows, use the import.
Nested files and which one wins
In a monorepo you can give each package its own AGENTS.md. The agents.md site sets the rule: the file closest to the edited file wins, and your chat prompt overrides them all. Three agents load nested files in three ways:
- Claude Code loads the files in your working directory and each directory above it at launch, and joins them from the root down, so it reads the closest file last. It adds a subdirectory's file once Claude opens a file in that subdirectory.
- Codex starts at the project root (in most repositories, the Git root) and walks down to the directory you started it in. It takes one file per directory,
AGENTS.override.mdahead ofAGENTS.md, and joins them root first, so later files override earlier ones. It stops adding files at 32 KiB in total, the default forproject_doc_max_bytes. - OpenCode searches up from the directory you start it in. Give it both
AGENTS.mdandCLAUDE.mdand it usesAGENTS.mdalone.
Codex's startup instructions stop at the directory you start it in. Start Codex at the repository root and a package's AGENTS.md stays out of them, while Claude Code would load the same file once it opened something in that package. Start Codex in the package when its rules matter.
Claude Code reads one more file: an organisation-wide CLAUDE.md that IT can install, on macOS at /Library/Application Support/ClaudeCode/CLAUDE.md. It loads before your personal and project files, and you can't exclude it.
Keep it lean
Claude Code reads your project's CLAUDE.md in full at launch and keeps it in context for the whole session, reading it again after /compact. Anthropic's guidance is to keep each one under 200 lines: "Longer files consume more context and reduce adherence." Imports change nothing here, because an imported file loads with the file that imports it.
- Keep the commands an agent can't guess: build, test and lint, with their exact flags.
- Write rules you can check: "Run
npm testbefore committing", where a vaguer file says "Test your changes". The example is Anthropic's. - Move rules for one part of the code out of the root file. Claude Code loads a rule in
.claude/rules/with apathsfield once Claude reads or edits a matching file. For other agents, put a nestedAGENTS.mdin the package that needs it, and mind the Codex gap above. - Leave out what the agent can read for itself: a tour of the folders, a list of dependencies, style rules your linter enforces.
In Claude Code, /doctor prompt-audit checks your CLAUDE.md and AGENTS.md files for outdated or conflicting instructions and proposes edits. It changes nothing until you ask.
A lean file leaves more of your plan for the work; our usage limits guide covers the rest of what loads at startup. The saving counts most on a local model. Ollama gives a model a 4k-token context on a Mac with under 24 GB of GPU memory, and ket's own AGENTS.md, measured below at about 1,300 tokens, would fill a third of it. Our Ollama guide shows how to set the context length before you start.
A measured trim
We tried this on a copy of the AGENTS.md in ket's own repository. Its six sections each give a rule and the reasons behind it. We kept every rule and every command, and cut the reasons:
| Before | After | |
|---|---|---|
| Lines | 114 | 56 |
| Bytes | 5,177 | 1,979 |
| Estimated tokens | 1,294 | 494 |
That's 62% fewer bytes to load in each session. The longest section, which keeps test runs out of the user's real data directory, went from 2,333 bytes to 879. We counted bytes with wc -c and estimated tokens at four bytes each, the rule of thumb ket uses for command output.
Cutting the reasons has a cost. An agent leans on them for cases a rule doesn't spell out, and we haven't measured whether agents follow the shorter file as well as the long one.
Check what each agent loaded
- Claude Code: run
/contextand look under Memory files, or look for the "AGENTS.md loaded" line when Claude Code readsAGENTS.mdon its own./memorylists your files and opens them in your editor. - Gemini CLI:
/memory showprints the combined instructions. - Codex: ask it to sum up what it read, as its docs suggest.
$ codex --ask-for-approval never "Summarize the current instructions."How ket does this
ket runs each task's agent in a worktree of its own. A worktree is a full checkout, so a committed AGENTS.md, with its CLAUDE.md import or symlink, is in each worktree for whichever agent you start there.
Untracked files stay behind. A gitignored CLAUDE.local.md exists in the checkout where you made it and nowhere else. Claude Code's docs suggest importing a file from your home directory instead. Or have ket copy it when it provisions a worktree: add it to files in the [provision] section of config.toml, keeping the default entries, since your list replaces them:
[provision]
files = [".env", ".env.local", ".env.*.local", "CLAUDE.local.md"]ket weighs each worktree's instruction files too. Hover a worktree's usage ring in the sidebar: when its CLAUDE.md runs past 200 lines, or its AGENTS.md passes the project_doc_max_bytes you've set for Codex, the card says so. A worktree within budget shows nothing. How provisioning works.
Related guides
Make your Claude Code usage limits last longer.
How the five-hour and weekly limits work, and the habits that make them last.
Run local models with Ollama and OpenCode.
Run Ollama local models as a coding agent in OpenCode, and hand the hard tasks to a cloud model.
Run coding agents in parallel without sharing a working directory.
How to split work between agents, watch them, and merge the results one at a time, smallest dependency first.
Set up a Git worktree for a coding agent.
Dependencies, .env files, ports and databases: what a fresh worktree is missing and how to fill it in.