Guide
AGENTS.md, CLAUDE.md and GEMINI.md: one instructions file for three CLIs
Claude Code, Codex CLI and Gemini CLI each look for a different file in different places. Here is what each one reads today, and a setup where you write your project rules once.
Which instructions file does each CLI read?
All three treat these files as context added to the conversation, not as enforced settings. The details differ more than the names suggest.
| Claude Code | Codex CLI | Gemini CLI | |
|---|---|---|---|
| Project file | CLAUDE.md or .claude/CLAUDE.md | AGENTS.md | GEMINI.md |
Reads AGENTS.md? | Yes, from v2.1.277, when there is no CLAUDE.md; or always through an @AGENTS.md import | Yes, natively | Only if listed in context.fileName |
| User-level file | ~/.claude/CLAUDE.md (plus ~/.claude/rules/) | ~/.codex/AGENTS.md (or CODEX_HOME) | ~/.gemini/GEMINI.md |
| Personal or override file | CLAUDE.local.md, meant to be gitignored | AGENTS.override.md wins over AGENTS.md in the same folder | Not documented |
| Folders | Working directory and every parent at launch; subfolder files load when Claude works there | Repo root down to the working directory, one file per folder | Workspace folders and parents up to .git; more files load when a tool touches a folder |
| Imports | @path, up to four hops deep | Not documented | @file.md, relative or absolute |
| Size guidance | Aim for under 200 lines; a file over 4 MiB is skipped | Stops adding files at 32 KiB combined by default (project_doc_max_bytes) | No size limit documented; searches up to 200 folders |
| Check what loaded | /context all or /memory | Ask it to summarize the current instructions | /memory show |
In all three, files are combined rather than replacing each other. Claude Code and Codex put the file closest to your working directory last. Codex says closer files override earlier guidance; Anthropic warns that Claude may follow either of two conflicting instructions. Don’t let your files contradict each other.
Does Claude Code read AGENTS.md?
Yes, with conditions. From v2.1.277 a built-in plugin reads AGENTS.md as your project instructions, but under the default setting only when none of CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in your working directory or above it. Your ~/.claude/CLAUDE.md and .claude/rules/ don’t count for that check and keep loading alongside.
- If both files exist, Claude reads only
CLAUDE.md, unless it importsAGENTS.mdor you set Project instructions in/configtoclaude-md-and-agents-md. - Adding a
CLAUDE.local.mdfor your own notes stops Claude from readingAGENTS.mdby default. - Claude Code doesn’t read
AGENTS.override.md,AGENTS.local.mdor anything under.agents/. - Some sessions can’t read
AGENTS.mddirectly, such as older versions. An@AGENTS.mdimport works there, and Anthropic says keeping the import never makes Claude read the file twice.
How Codex CLI finds AGENTS.md
Codex builds its instruction chain once at startup. It reads the global file first: AGENTS.override.md in ~/.codex if it exists and isn’t empty, otherwise AGENTS.md. Then it walks from the project root, usually the git root, down to your working directory. In each folder it takes the first of AGENTS.override.md, AGENTS.md and any names in project_doc_fallback_filenames.
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536
Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default. Restart Codex after changing the config.
How to make Gemini CLI read AGENTS.md
Gemini CLI loads ~/.gemini/GEMINI.md, then GEMINI.md files in your workspace and its parent folders, then files it finds when a tool opens a folder. The context.fileName setting takes one name or a list. Put it in the project’s .gemini/settings.json, or in ~/.gemini/settings.json to apply it everywhere:
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}
If you turn on Gemini CLI’s Trusted Folders feature, an untrusted folder’s .gemini/settings.json is ignored. Use the user-level settings file if the setting has to apply before you trust a folder.
How do I use one instructions file for Claude Code, Codex and Gemini?
- Write AGENTS.md at the repo rootThis is the shared file. Codex reads it with no setup.
- Add a one-line CLAUDE.mdPut
@AGENTS.mdon the first line. Add Claude-only notes below it if you need them. This works even in sessions that can’t readAGENTS.mddirectly, and keeps working if you later add aCLAUDE.local.md. - Point Gemini CLI at itSet
context.fileNameto includeAGENTS.md, as shown above, and commit.gemini/settings.jsonif your team uses Gemini CLI. - Check each toolRun
/context allin Claude Code,codex --ask-for-approval never "Summarize the current instructions."in the repo root, and/memory showin Gemini CLI.
# CLAUDE.md
@AGENTS.md
## Claude Code
Use plan mode for changes under src/billing/.
Why not a symlink?
Anthropic documents ln -s AGENTS.md CLAUDE.md as an option, with two catches. Claude’s Edit and Write tools refuse to write through a symlink. And on Windows, creating a symlink needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a plain text file unless core.symlinks is on, so that clone gets a one-line CLAUDE.md instead of your rules. Microsoft’s “Create symbolic links” policy is granted only to Administrators by default. If anyone on the team uses Windows, use the import.
What to put in AGENTS.md, and what to leave out
Write down what you would otherwise re-explain each session. Keep it concrete enough to check: “Run npm test before committing” beats “test your changes”.
- Put in: the exact build, test and lint commands; conventions that differ from the usual defaults; where key code lives when it isn’t obvious; folders and files not to touch; how to tell a change is done.
- Leave out: API keys, tokens, passwords and internal URLs you wouldn’t publish. The file is usually committed, and its text goes to the model provider with every request.
- Leave out: long step-by-step procedures. Anthropic suggests moving them into a skill or a path-scoped rule.
- Leave out: anything the agent can read from the code, such as directory listings and dependency lists.
- Move elsewhere: personal preferences go in the user-level file or
CLAUDE.local.md, not the shared one.
# AGENTS.md
## Commands
- Install: pnpm install
- Test: pnpm test (run before every commit)
- Lint: pnpm lint
## Conventions
- API responses use camelCase.
- New tests go in tests/ and use Vitest.
## Do not touch
- legacy/ and anything under generated/
Instructions are guidance, not a lock. To block an action every time, Anthropic points to hooks and permission settings rather than CLAUDE.md.
Skills: SKILL.md folders in each CLI
A skill is a folder with a SKILL.md file: YAML frontmatter with a description, then instructions. Unlike the instructions file, a skill loads only when it’s relevant. All three CLIs support skills today, but not in the same folders.
| User skills | Project skills | |
|---|---|---|
| Claude Code | ~/.claude/skills/<name>/SKILL.md | .claude/skills/<name>/SKILL.md |
| Codex CLI | ~/.agents/skills | .agents/skills in the working directory, the folder above it, and the repo root |
| Gemini CLI | ~/.gemini/skills or ~/.agents/skills | .gemini/skills or .agents/skills |
A .agents/skills folder covers Codex and Gemini CLI. Claude Code doesn’t read .agents/, so it needs its own copy under .claude/skills. Codex requires both name and description in the frontmatter.
Where Pyloxa fits
Pyloxa is a free Windows desktop app that runs Claude Code and Codex CLI, with Gemini CLI as experimental support, on one project. Its shared memory is one store on your computer that all three receive as background when Pyloxa dispatches work: rules, preferences, decisions, facts and pitfalls. Agents can suggest new memories while they work, but a suggestion goes to Pending and counts only after you accept it. Every shared-memory feature is free.
- Sync to CLIs writes the project’s memory as a marked Pyloxa block in
AGENTS.mdand adds@AGENTS.mdtoCLAUDE.md, the same setup as above. You see the diff first, and Pyloxa never commits for you. - Writing to each CLI’s user-level memory (
~/.claude/CLAUDE.md,~/.codex/AGENTS.md,~/.gemini/GEMINI.md) is off by default; when you turn it on, Pyloxa backs those files up before its first write. - You can import from files you already have, such as
CLAUDE.md,.claude/rules/*.md,AGENTS.mdandGEMINI.md. Pyloxa only reads them. - The Skills inventory, which shows which skills each CLI can see, is free. A skills library in
~/.agents/skillssynced to every CLI, and choosing skills per project or profile, are Pro.
If you use one CLI, or the AGENTS.md plus import setup already does what you need, you don’t need Pyloxa for this.
FAQ
Does Codex read CLAUDE.md?
AGENTS.override.md, AGENTS.md and any names you add to project_doc_fallback_filenames in ~/.codex/config.toml, and it uses at most one file per folder. Making AGENTS.md the main file avoids the question.I have both CLAUDE.md and AGENTS.md. Which one does Claude Code use?
CLAUDE.md. Add @AGENTS.md to it, or set Project instructions in /config to claude-md-and-agents-md to load both.Why did Claude Code stop reading my AGENTS.md?
CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or a parent folder. A version before v2.1.277, or a disabled AGENTS.md plugin, has the same effect. A CLAUDE.md that imports AGENTS.md fixes all of these.Can GEMINI.md import other files?
@./path/file.md where you want the file’s text; relative and absolute paths both work. Use /memory show to see the combined result.Can I put API keys in AGENTS.md?
Sources
- How Claude remembers your project, Anthropic (checked 2026-11-19)
- Extend Claude with skills, Anthropic (checked 2026-11-19)
- Custom instructions with AGENTS.md, OpenAI (checked 2026-11-19)
- Build skills, OpenAI (checked 2026-11-19)
- Provide context with GEMINI.md files, Google (checked 2026-11-19)
- Gemini CLI configuration, Google (checked 2026-11-19)
- Trusted Folders, Google (checked 2026-11-19)
- Agent Skills, Google (checked 2026-11-19)
- Create symbolic links, Microsoft (checked 2026-11-19)