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 CodeCodex CLIGemini CLI
Project fileCLAUDE.md or .claude/CLAUDE.mdAGENTS.mdGEMINI.md
Reads AGENTS.md?Yes, from v2.1.277, when there is no CLAUDE.md; or always through an @AGENTS.md importYes, nativelyOnly 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 fileCLAUDE.local.md, meant to be gitignoredAGENTS.override.md wins over AGENTS.md in the same folderNot documented
FoldersWorking directory and every parent at launch; subfolder files load when Claude works thereRepo root down to the working directory, one file per folderWorkspace folders and parents up to .git; more files load when a tool touches a folder
Imports@path, up to four hops deepNot documented@file.md, relative or absolute
Size guidanceAim for under 200 lines; a file over 4 MiB is skippedStops 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 /memoryAsk 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 imports AGENTS.md or you set Project instructions in /config to claude-md-and-agents-md.
  • Adding a CLAUDE.local.md for your own notes stops Claude from reading AGENTS.md by default.
  • Claude Code doesn’t read AGENTS.override.md, AGENTS.local.md or anything under .agents/.
  • Some sessions can’t read AGENTS.md directly, such as older versions. An @AGENTS.md import 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?

  1. Write AGENTS.md at the repo rootThis is the shared file. Codex reads it with no setup.
  2. Add a one-line CLAUDE.mdPut @AGENTS.md on the first line. Add Claude-only notes below it if you need them. This works even in sessions that can’t read AGENTS.md directly, and keeps working if you later add a CLAUDE.local.md.
  3. Point Gemini CLI at itSet context.fileName to include AGENTS.md, as shown above, and commit .gemini/settings.json if your team uses Gemini CLI.
  4. Check each toolRun /context all in Claude Code, codex --ask-for-approval never "Summarize the current instructions." in the repo root, and /memory show in 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 skillsProject 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.md and adds @AGENTS.md to CLAUDE.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.md and GEMINI.md. Pyloxa only reads them.
  • The Skills inventory, which shows which skills each CLI can see, is free. A skills library in ~/.agents/skills synced 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?
Not by default. Codex looks for 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?
By default only 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?
The usual cause is a 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?
Yes. Add @./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?
No. The file is usually committed to the repository, and its contents go to the model provider as part of every request. Keep keys in the CLI’s own sign-in or your environment, and leave them out of instruction files.

Sources

  1. How Claude remembers your project, Anthropic (checked 2026-11-19)
  2. Extend Claude with skills, Anthropic (checked 2026-11-19)
  3. Custom instructions with AGENTS.md, OpenAI (checked 2026-11-19)
  4. Build skills, OpenAI (checked 2026-11-19)
  5. Provide context with GEMINI.md files, Google (checked 2026-11-19)
  6. Gemini CLI configuration, Google (checked 2026-11-19)
  7. Trusted Folders, Google (checked 2026-11-19)
  8. Agent Skills, Google (checked 2026-11-19)
  9. Create symbolic links, Microsoft (checked 2026-11-19)

Want this handled for you?

Pyloxa is a free Windows app that runs the Claude Code and Codex CLIs you already use: it splits the work by your rules, runs your tests itself and offers a handoff when one runs out of quota.