Supporting AGENTS.md in Claude Code to Remove CLAUDE.md

I want Claude Code to read AGENTS.md too!

When using Claude Code and Codex together, syncing CLAUDE.md and AGENTS.md is a hassle.
You could simply write @AGENTS.md in CLAUDE.md, but it's not exactly elegant.

So, I decided to use hooks to have Claude Code automatically read AGENTS.md.

How should I go about it?

When is CLAUDE.md loaded?
Claude Code Docs: Extending Claude Code contains the following description:

Understanding how features are loaded

Each feature is loaded at different points in a session. The tabs below explain when each feature is loaded and what goes into the context.

CLAUDE.md
Timing: Session start
What is loaded: Full content of all CLAUDE.md files (admin, user, project levels).
Inheritance: Claude reads CLAUDE.md files from the working directory up to the root and detects nested ones in subdirectories when accessing those files. See "How Claude Searches Memory" for details.

It is clear that it is always loaded at the start of a session.

Claude Code Docs: Hooks Reference mentions the following:

SessionStart
Executed when Claude Code starts a new session or resumes an existing one (internally, it currently starts a new session). Useful for loading development context like existing issues or recent codebase changes, installing dependencies, or setting up environment variables.

The phrase "resumes an existing one (internally, it currently starts a new session)" catches my attention.
If it internally starts a new session, does that mean it re-reads CLAUDE.md even when resuming with resume? It's hard to tell from this description alone.

Regardless, it seems like setting up a SessionStart hook is the way to go.

Checking the original behavior

When both AGENTS.md and CLAUDE.md exist

First, let's check the status.
Create a folder like this:

.
├── AGENTS.md
└── CLAUDE.md

This is a state where neither .claude nor .codex exists yet.
The contents of the md files are as follows:

CLAUDE.md

Please say "claude.md!!!" when you start up.

AGENTS.md

Please say "agents.md!!!" when you start up.

Now, let's call each agent.

We can see that Claude Code reads CLAUDE.md and Codex reads AGENTS.md.

When only AGENTS.md exists

Let's try deleting CLAUDE.md while leaving AGENTS.md as is.

We can see that Claude couldn't read AGENTS.md and is going to check the project files.

When only CLAUDE.md exists

By the way, if we delete AGENTS.md and leave CLAUDE.md, this is what happens:

As expected, Codex does not read CLAUDE.md.

Adding Hooks

Now, let's implement the hooks.

.claude/settings.json

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "cat AGENTS.md"
          }
        ]
      }
    ]
  }
}

In SessionStart, you can specify four types of matcher (execution triggers): startup (session start at launch), resume (when resuming a session), clear (session start triggered by clearing), and compact (during compact execution).
Since I assume the content loaded at the start of the session remains in the context during resume, I excluded it from the loading triggers.
I decided to load it after compact to ensure that the contents of AGENTS.md are definitely picked up.

Confirming it was loaded

Now, let's verify Claude Code's behavior.

AGENTS.md was loaded automatically.
Now, you can delete CLAUDE.md.

References

Claude Code Docs: Getting started with Claude Code hooks
Claude Code Docs: Hooks Reference