---
title: "Use AGENTS.md in Claude Code and Codex"
description: "Codex reads AGENTS.md by default. Claude Code 2.1.277 or later reads it when your project has no CLAUDE.md. To keep both, put @AGENTS.md in your CLAUDE.md."
canonical: "https://logbrew.co/en/guides/agents-md"
last_updated: "2026-11-10"
---

# Use AGENTS.md in Claude Code and Codex

Codex reads `AGENTS.md` by default. Claude Code 2.1.277 or later reads it when your project has no `CLAUDE.md`. To keep both, put `@AGENTS.md` in your `CLAUDE.md`.

Tested on November 10, 2026 with Claude Code 2.1.319 and Codex CLI 0.167.0

By [Furkan Erday](https://github.com/furkanerday). Furkan Erday is the founder of LogBrew. He builds LogBrew with Claude Code and Codex every day.

Canonical: https://logbrew.co/en/guides/agents-md

## When each agent loads `AGENTS.md`

| Your project has | Claude Code | Codex |
| --- | --- | --- |
| Only `AGENTS.md` | Loaded | Loaded |
| `AGENTS.md` and `CLAUDE.md` | Left out | Loaded |
| A `CLAUDE.md` that imports `@AGENTS.md` | Loaded | Loaded |
| A `CLAUDE.md` symlink to `AGENTS.md` | Loaded | Loaded |
| `AGENTS.md` and `CLAUDE.local.md` | Left out | Loaded |

We read the instructions each agent sent with its first request.

## Set up 1 file for both agents

### Write AGENTS.md at the project root

Put your build commands, test commands, and code rules in 1 file. Both agents read it from the root of your Git repository down to your current folder.

### Update Claude Code

Claude Code reads `AGENTS.md` itself from version 2.1.277. Older versions need the import in the next step.

```bash
claude update
```

### Import AGENTS.md from your CLAUDE.md

A `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` in your folder or above it stops Claude Code from reading `AGENTS.md`. Add this line to your `CLAUDE.md` to load both.

```bash
@AGENTS.md
```

### Or link CLAUDE.md to AGENTS.md

If your `CLAUDE.md` would hold only the import, make it a symlink instead.

```bash
ln -s AGENTS.md CLAUDE.md
```

### Or load both with a setting

To keep a `CLAUDE.local.md` and still load `AGENTS.md`, add this to `~/.claude/settings.json`. In a session, the Project instructions option in `/config` sets the same value.

```bash
{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}
```

### Check what Codex loaded

Run this from the folder you work in. The Codex docs give this command to make Codex repeat the instructions it loaded.

```bash
codex --ask-for-approval never "Summarize the current instructions."
```

## What we saw when we tested it

We pointed both agents at a local test server and read the instructions each one sent with its first request. That shows exactly which files each agent loads.

Claude Code loaded `AGENTS.md` when the project had no `CLAUDE.md`, and its debug log said `no CLAUDE.md found; AGENTS.md loaded`. With a `CLAUDE.md` beside it, Claude Code left `AGENTS.md` out. With the `@AGENTS.md` import or the symlink, the `AGENTS.md` text appeared exactly once.

The `pluginConfigs` setting above loaded both files, also with a `CLAUDE.local.md` in the project.

Codex loaded `~/.codex/AGENTS.md` first, then the root `AGENTS.md`, then the file in the current folder. An `AGENTS.override.md` replaced the `AGENTS.md` in its folder. Codex skipped a `CLAUDE.md` until we added it to `project_doc_fallback_filenames`. When both files existed, Codex loaded only `AGENTS.md`, even with the fallback set.

## AGENTS.md vs CLAUDE.md

Codex reads `AGENTS.override.md` or `AGENTS.md` in each folder, plus the global `~/.codex/AGENTS.md`, up to 32 KiB in total by default. It reads `CLAUDE.md` only if you list it in `project_doc_fallback_filenames`.

Claude Code reads `CLAUDE.md` first. It reads `AGENTS.md` and `.claude/AGENTS.md` only when no project `CLAUDE.md` applies. Your personal `~/.claude/CLAUDE.md` does not count, so it loads beside `AGENTS.md`.

## What the GitHub reports say

#6235, with 409 comments, asked Claude Code to support AGENTS.md. On 17 August 2026 an Anthropic engineer closed it with the import and the symlink above. Claude Code now reads the file itself. #31005 asks for `.agents/skills/` support as well and is still open.

## Questions people ask

### Does Claude Code read AGENTS.md?

Yes, from version 2.1.277, when no `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists in your folder or above it. We confirmed it on 2.1.319.

### Should I use AGENTS.md or CLAUDE.md?

Use `AGENTS.md` if anyone on your team uses Codex or another agent. Keep a `CLAUDE.md` only for rules that apply to Claude Code alone, and import `@AGENTS.md` from it.

### Can I symlink CLAUDE.md to AGENTS.md?

Yes. In our test, Claude Code loaded the linked file once, the same as the import.

### Does Codex read CLAUDE.md?

Not by default. Add `project_doc_fallback_filenames = ["CLAUDE.md"]` to `~/.codex/config.toml`.

## Give your agent your production errors

Connect the LogBrew MCP server, and Claude Code or Codex reads the errors, logs, and traces of the projects you approve. Start on the generous free tier, no card needed.

[Connect Your Agent](https://logbrew.co/en/agents)

## Sources

- [Claude Code docs, How Claude remembers your project](https://code.claude.com/docs/en/memory#agents-md)
- [Codex docs, Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
- [anthropics/claude-code#6235](https://github.com/anthropics/claude-code/issues/6235)
- [anthropics/claude-code#31005](https://github.com/anthropics/claude-code/issues/31005)

## More guides for AI coding agents

- [Add an MCP server to Claude Code and Codex](https://logbrew.co/en/guides/mcp-server-claude-code-codex)
- [Fix the Claude overloaded error 529 and rate limit error 429](https://logbrew.co/en/guides/claude-overloaded-rate-limit-error)
- [How to fix errors in Claude Code, Codex, and browser JavaScript](https://logbrew.co/en/guides)