Skip to content

fix: migrate to AGENTS.md #764

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
+24 −11
Open

fix: migrate to AGENTS.md #764

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cf27bde
fix: migrate to AGENTS.md
fouad-openai Apr 30, 2025
57adfb5
fix: readme
fouad-openai Apr 30, 2025
d1bc345
fix: readme ascii
fouad-openai Apr 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -226,13 +226,15 @@ Key flags: `--model/-m`, `--approval-mode/-a`, `--quiet/-q`, and `--notify`.

## Memory & Project Docs

Codex merges Markdown instructions in this order:
Codex looks for Markdown agent files (preferred: `AGENTS.md`) in the following order and merges them top-down:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change: "You can give Codex extra instructions and guidance using AGENTS.md files. Codex looks for AGENTS.md files in the following places, and merges them top-down:"


1. `~/.codex/instructions.md` - personal global guidance
2. `codex.md` at repo root - shared project notes
3. `codex.md` in cwd - sub-package specifics
1. `~/.codex/AGENTS.md` - personal global guidance
2. `AGENTS.md` at repo root - shared project notes
3. `AGENTS.md` in the current working directory - sub-folder/feature specifics

Disable with `--no-project-doc` or `CODEX_DISABLE_PROJECT_DOC=1`.
Disable loading of these files with `--no-project-doc` or the environment variable `CODEX_DISABLE_PROJECT_DOC=1`.

For backwards-compatibility with older Codex versions, `instructions.md` and `codex.md` are still supported but `AGENTS.md` is recommended.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change: remove this from the docs.


---

Expand Down Expand Up @@ -437,7 +439,7 @@ Below is a comprehensive example of `config.json` with multiple custom providers

### Custom Instructions

You can create a `~/.codex/instructions.md` file to define custom instructions:
You can create a `~/.codex/AGENTS.md` file to define custom guidance for the agent:

```markdown
- Always respond with emojis
Expand Down
4 changes: 2 additions & 2 deletions codex-cli/src/cli.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ const cli = meow(
--auto-edit Automatically approve file edits; still prompt for commands
--full-auto Automatically approve edits and commands when executed in the sandbox

--no-project-doc Do not automatically include the repository's 'codex.md'
--no-project-doc Do not automatically include the repository's 'AGENTS.md'
--project-doc <file> Include an additional markdown file at <file> as context
--full-stdout Do not truncate stdout/stderr from command outputs
--notify Enable desktop notifications for responses
Expand Down Expand Up @@ -144,7 +144,7 @@ const cli = meow(
},
noProjectDoc: {
type: "boolean",
description: "Disable automatic inclusion of project-level codex.md",
description: "Disable automatic inclusion of project-level AGENTS.md",
},
projectDoc: {
type: "string",
Expand Down
17 changes: 14 additions & 3 deletions codex-cli/src/utils/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -192,12 +192,22 @@ export type AppConfig = {
export const PRETTY_PRINT = Boolean(process.env["PRETTY_PRINT"] || "");

// ---------------------------------------------------------------------------
// Project doc support (codex.md)
// Project doc support (AGENTS.md / codex.md)
// ---------------------------------------------------------------------------

export const PROJECT_DOC_MAX_BYTES = 32 * 1024; // 32 kB

const PROJECT_DOC_FILENAMES = ["codex.md", ".codex.md", "CODEX.md"];
// We support multiple filenames for project-level agent instructions. As of
// mid-2024 the recommended convention is to use `AGENTS.md`, however we keep
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2025

// the legacy `codex.md` variants for backwards-compatibility so that existing
// repositories continue to work without changes. The list is ordered so that
// the first match wins – newer conventions first, older fallbacks later.
const PROJECT_DOC_FILENAMES = [
"AGENTS.md", // preferred
"codex.md", // legacy
".codex.md",
"CODEX.md",
];
const PROJECT_DOC_SEPARATOR = "\n\n--- project-doc ---\n\n";

export function discoverProjectDocPath(startDir: string): string | null {
Expand Down Expand Up @@ -238,7 +248,8 @@ export function discoverProjectDocPath(startDir: string): string | null {
}

/**
* Load the project documentation markdown (codex.md) if present. If the file
* Load the project documentation markdown (`AGENTS.md` – or the legacy
* `codex.md`) if present. If the file
* exceeds {@link PROJECT_DOC_MAX_BYTES} it will be truncated and a warning is
* logged.
*
Expand Down