Learn how a single agents.md file keeps Codex, Claude, and Copilot in sync, with step-by-step guidance, best practices, and a comparison of AI coding tools.

Agents File Unlocked: How I Keep Codex, Claude, and Copilot on Point

Q: How do I know if the file is being used?

Run codex --show-instructions to see the merged instruction chain. It will list the file path it read.

Published by Brav

Table of Contents

TL;DR

An agents.md file is the cheat-sheet your AI coding assistants read before they touch your code.
With Codex CLI’s /init you can spin up a ready-to-go agents.md in minutes.
A single, version-controlled file keeps all your agents on the same page—no more out-of-date commands or style mismatches.
The file is structured like a README but for machines: sections for project layout, build/test commands, and coding style.
Keep it up-to-date whenever you add a new library, change your test framework, or update your style guide.

Why this matters

I’ve spent years in the trenches where the same codebase lives in three worlds at once: the IDE, the CI pipeline, and the AI assistant that writes the next feature. Each world has its own set of rules. When an AI sees a project, it has no idea whether your tests run with npm test or pnpm run test. It may try to run yarn test and hit a missing lockfile. When you pull a PR, the linter might flag a line that the AI never cared about.

That friction is the pain points we all feel:

Context drift – The AI can’t read the current folder structure or test scripts.
Style mismatches – Generated code violates the team’s style guide.
Outdated commands – New build scripts aren’t recognized by the agent.
Multiple tools – Each AI has its own way of asking for instructions, so you juggle several config files.

A single, well-maintained agents.md solves all of that. It gives the AI a single source of truth. Think of it as the project’s “instruction manual” for machines, just as a README is for humans.

Core concepts

An agents file is a plain-text Markdown document that lives in the project root. Its job is to tell an AI:

Where the code lives.
How to build and test it.
What coding style to use.
Any other guidelines the team cares about (naming, commit conventions, security hints).

OpenAI’s own documentation calls it the primary project context file for Codex CLI. It is discovered automatically when you run a Codex command in or below the repository root, and it takes precedence over global defaults. The discovery logic is spelled out in the official guide: first it checks the global home folder, then the current directory, then any fallback names like project_doc_fallback_filenames. This guarantees that the file is always found if you’re inside the repo. OpenAI Codex Guide

The DeepWiki article gives a step-by-step of how the /init command scans the code base and creates a template file. The template includes sections for project overview, technology stack, key files, development guidelines, and a recent changes log. That is the skeleton that you then tweak. DeepWiki Agent Config

Below is a quick table that compares the same idea across three popular AI coding tools. It shows the file name, where it lives, and its major limitation.

Parameter	Use Case	Limitation
agents.md	Codex CLI – reads the file from the repo root and uses it to guide all code-generation and run-commands.	Must be kept in sync with local changes; otherwise Codex defaults to global settings.
.claude/agents/*.md	Claude Code – sub-agents defined per-project; each file has a YAML front-matter that tells the agent its purpose.	Requires the agent to be enabled in the CLI; files are not automatically merged.
copilot-instructions.md	GitHub Copilot – a Markdown file that sets custom instructions for the assistant, e.g., always use semicolons.	Copilot doesn’t run commands; the file is purely for text suggestions.

How to apply it

1. Install Codex CLI

If you don’t already have it, run:

npm i -g @openai/codex

The CLI will pull the latest binary for your OS. The official page shows you the install steps and the minimal requirements. OpenAI Codex Guide

2. Run the init command

Navigate to the root of your repo and type:

codex init

The tool scans the directory tree. It looks for package.json, tsconfig.json, .gitignore, test folders, and any build scripts. It then writes a agents.md that looks something like this:

# Project overview
This is a React-TS monorepo.

## Technology stack
- React 18
- TypeScript 5
- Vite 4

## Key files
- app/ – UI components
- tests/ – unit tests

## Development guidelines
- Use PascalCase for component names.
- Run pnpm test to execute tests.

## Recent changes
- 2025-08-12: Added ESLint 8.

The file is automatically committed to your repo as you finish editing. The DeepWiki guide notes that the file is created in the project root and that the init command can be re-run to refresh any sections. DeepWiki Agent Config

3. Edit personal preferences

Open the file and adjust anything that is specific to your team:

Approve commands – If you want Codex to ask before running npm run build, add approval: never to the build section.
Coding style – Add a style: PascalCase entry or a link to your style guide.
Test runner – Replace pnpm test with yarn test if that’s what your CI uses.
Add custom sections – You can create a security guidelines section or a docs section that the agent can reference.

The file is just Markdown, so feel free to use bullets, code fences, and any formatting that helps you read it.

4. Commit and push

After you’re happy, commit the file and push it to the repo:

git add agents.md
git commit -m Add agents file for Codex
git push

Commiting ensures that other developers and Codex Cloud see the same context. Codex Cloud automatically downloads the repo before running any cloud task, so the file will be there. If you forget to commit, the cloud job will fall back to the global default, which can lead to mismatched code.

5. Keep it up-to-date

Every time you add a new package, change your test framework, or update your linting rules, edit the agents.md file. A good rule of thumb is to run codex init once a month or whenever you make a structural change. The command will merge new information without wiping your manual edits.

6. Use the file in other tools

Claude Code looks for sub-agent files in .claude/agents/. You can mirror the sections of agents.md into a my-agent.md file inside that folder. The Anthropic guide explains the file format: a YAML front-matter followed by instructions. Anthropic Subagents Guide

GitHub Copilot reads copilot-instructions.md. If you want to give Copilot the same style guidance, copy the relevant parts of your agents.md into that file. The Medium article demonstrates that adding a copilot-instructions.md can reduce boilerplate code. Copilot Instructions

Pitfalls & edge cases

Issue	Why it happens	How to fix
Outdated commands	The file still references npm test while you now use pnpm test.	Run codex init again or manually edit the section.
Overwriting the file	Re-running /init overwrites manual edits.	Keep a copy of the manual section and use –no-overwrite if available.
Global vs. project scope	Codex finds a global agents.md that conflicts with the project one.	Remove the global file or use the –global flag to enforce project scope.
Approval mode mismatch	The file says approval: never but you want confirmation.	Adjust the approval field.
Missing sections	The agent complains about missing build commands.	Add a placeholder command (# placeholder) to satisfy the syntax.

Open questions that often surface:

How often should I update the file? Keep it in sync with any new tech stack changes; a quarterly review works for most teams.
Can I mix global and project files? Yes—global files are used first, then the project file overrides them.
What happens if I delete the file? Codex falls back to defaults, which may run unexpected commands or ignore style guidelines.

Quick FAQ

Q1: What exactly is an agents.md file? A: It’s a Markdown file that tells an AI how the codebase is built, tested, and styled.

Q2: Do I need to keep it in the repo? A: Absolutely. It must live in the repo root so every local clone and the cloud environment can read it.

Q3: Can I use it with other AI tools? A: Yes. Claude Code uses .claude/agents/*.md, and Copilot uses copilot-instructions.md. The concepts are the same; just adapt the format.

Q4: What if the file becomes too big? A: Codex truncates after 32 KiB by default. Split the file into multiple smaller sections or use fallback names.

Q5: How do I know if the file is being used? A: Run codex –show-instructions to see the merged instruction chain. It will list the file path it read.

Conclusion

Your AI coding assistants are only as good as the context you give them. A single, version-controlled agents.md file keeps Codex, Claude, and Copilot aligned, reduces friction, and saves you from stale commands. Treat it like a living doc: run codex init when you add a new library, edit the file when your style guide changes, and commit it every time. If you’re a team that already uses multiple AI tools, start by aligning the core sections—project layout, build/test commands, and coding style. From there you’ll see consistent output, fewer mismatched commits, and a smoother developer experience.