Harness Notes

Codex reads AGENTS.md, plus AGENTS.override.md, which takes the place of AGENTS.md in the same directory. Extra names listed in project_doc_fallback_filenames (e.g. ["TEAM_GUIDE.md", "CLAUDE.md"]) are tried only in project directories that have neither file. There is no rules directory, and it does not read CLAUDE.md unless you list it.

Fallback names apply only to project directories, not to ~/.codex.

Fallback entries must be plain file names; entries containing / are ignored.

Claude Code reads CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md (personal, gitignored), every .md under .claude/rules/ (recursively) and ~/.claude/rules/, plus ~/.claude/CLAUDE.md and a managed-policy CLAUDE.md. Since v2.1.277 it also reads AGENTS.md and .claude/AGENTS.md, by default only as a fallback when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or above. It never reads AGENTS.local.md, AGENTS.override.md or anything under .agents/.

~/.claude/CLAUDE.md, the managed CLAUDE.md and .claude/rules/ files don't count as a CLAUDE.md for the AGENTS.md fallback check; adding a CLAUDE.local.md does, and stops AGENTS.md loading.

Project rules are .mdc files under .cursor/rules/ (subfolders allowed; plain .md files there are ignored). The CLI also reads AGENTS.md, CLAUDE.md and CLAUDE.local.md, the legacy .cursorrules file at the repo root, user rule files in ~/.cursor/rules/, plus User Rules and Team Rules stored on your Cursor account.

.cursorrules is deprecated; it is still loaded as an always-applied rule.

~/.claude/CLAUDE.md, .claude/rules/ and GEMINI.md are not read.

Only AGENTS.md. V2 reads ~/.config/opencode/AGENTS.md and AGENTS.md files in the project; it has no CLAUDE.md fallback.

Pi reads context files named AGENTS.override.md, AGENTS.md, AGENTS.MD, CLAUDE.md or CLAUDE.MD, using only the first one it finds in each directory, in that order. Separately, SYSTEM.md replaces Pi's default system prompt and APPEND_SYSTEM.md adds to it; both live in ~/.pi/agent/ or the project's .pi/ folder. There is no rules directory.

AGENTS.override.md only replaces the other file in the same directory. Context files in other directories still load.

Global: ~/.codex (or $CODEX_HOME). Project: every directory from the project root (the nearest parent containing .git, or any marker set in project_root_markers) down to the current working directory; with no root found, only the working directory is checked. Files are read when the session starts. Files in subdirectories below the working directory are never loaded automatically. Codex's built-in prompt only tells the model to look for them itself when it works there.

In an untrusted project Codex skips project AGENTS.md files entirely and keeps only the global file.

project_root_markers = [] stops the upward search, so only the working directory is checked.

Codex reads project_root_markers from user, system and managed config only; a project's own .codex/config.toml can't change it.

At launch it loads the managed file (macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux/WSL /etc/claude-code/CLAUDE.md, Windows C:\Program Files\ClaudeCode\CLAUDE.md), ~/.claude/CLAUDE.md, and the CLAUDE.md/CLAUDE.local.md files in the working directory and every directory above it up to the filesystem root. Files in subdirectories below the working directory load on demand, the first time Claude reads, writes or edits a file in that subdirectory (including a single-file cat/head via Bash). A subdirectory AGENTS.md loads when Claude opens a file there with the Read tool and that subdirectory has no CLAUDE.md file of its own.

Directories added with --add-dir don't contribute instruction files unless CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 is set, and even then their AGENTS.md doesn't load.

Subdirectory files and path-scoped rules don't appear under Memory files in /context; a Loaded line with the path appears in the terminal when they load.

At startup the CLI walks from the workspace directory up to the filesystem root, loading .cursor/rules/, AGENTS.md, CLAUDE.md and CLAUDE.local.md from each directory, so ~/.cursor/rules/ and ~/AGENTS.md apply when you work under your home folder. It also scans subdirectories at startup for nested .cursor/rules/, AGENTS.md and CLAUDE.md (skipping folders such as node_modules, dist and build); nested files apply when the agent works with files in that directory or below. .cursorrules is read only from the git repo root.

The docs describe CLAUDE.md and AGENTS.md at the project root and in subdirectories; the CLI's walk up through parent directories is wider than the editor docs suggest.

At startup it loads ~/.config/opencode/AGENTS.md (or $OPENCODE_CONFIG_DIR/AGENTS.md) and every AGENTS.md from the workspace directory up to your home directory, or up to the project root if the workspace is outside home. AGENTS.md files below the workspace are added during the session when the agent reads a file or lists a directory in that area.

If the workspace is outside the project root, only the global file is loaded.

Inside home the walk can go past the repository root, so an AGENTS.md in ~/code/ or ~ is loaded too.

At startup Pi loads one file from the agent directory (~/.pi/agent, or $PI_CODING_AGENT_DIR), then one from the working directory and from every parent directory up to the filesystem root. Files in subdirectories below the working directory are never loaded, not even when Pi works on files there. SYSTEM.md and APPEND_SYSTEM.md are read only from <cwd>/.pi/ and ~/.pi/agent/, not from parent directories.

If a linked git worktree sits inside its main checkout, the worktree's own context file replaces the main repo's copy so the same instructions don't load twice.

All applicable files are concatenated: the global file first, then project files from the root down to the working directory, separated by blank lines (with a --- project-doc --- marker before the first project file). Nothing is merged or deduplicated. Closer files appear later and win by convention, and in each directory only the first of AGENTS.override.md, AGENTS.md and fallback names is used.

Instructions you type in the prompt, and developer_instructions, take precedence over AGENTS.md according to Codex's built-in prompt.

Every applicable file is concatenated into context; nothing overrides anything. Order is managed, user, then project files from the filesystem root down to your working directory, with CLAUDE.local.md after CLAUDE.md in each directory and user rules before project rules, so the most specific text comes last. If two instructions conflict, Claude may follow either one, so keep them consistent; with claude-md-and-agents-md mode each directory's CLAUDE.md files come before its AGENTS.md.

CLAUDE.md content is sent as a user message after the system prompt, and Claude treats it as guidance, not enforced configuration; use hooks or permissions for hard rules.

All applicable rules are merged into the context; none replaces another. When guidance conflicts, Team Rules beat Project Rules, which beat User Rules, and a nested AGENTS.md takes precedence over the ones in its parent directories. Two rule files with the same name in different folders both apply.

All applicable files are combined, not overridden: the global file first, then project files nearest-first, each as an Instructions from: <path> block after the agent prompt and environment context. Nested files found later are added to the session history in discovery order, and OpenCode does not resolve conflicts between them.

Every context file found is added in full to the system prompt, each in its own block labelled with its path, in this order: agent-directory file first, then from the filesystem root down to the working directory. Pi does not resolve conflicts, so the model sees all of them; the file closest to the working directory comes last. A trusted project .pi/SYSTEM.md or .pi/APPEND_SYSTEM.md replaces the user file of the same name rather than being combined with it.

Project files share a combined budget of project_doc_max_bytes (default 32 KiB = 32768 bytes). The file that crosses the limit is cut off at the byte limit, and any later, deeper files are dropped. The only notice is a warning in the log. The global ~/.codex/AGENTS.md doesn't count toward this budget.

Raise it with project_doc_max_bytes = 65536 in config.toml or -c project_doc_max_bytes=65536.

Because the root file is read first, an oversized root file can push out deeper, more specific files.

Some config docs describe the limit as per file; in 0.162.1 the budget is shared by all project files.

Claude Code loads a CLAUDE.md of up to 4 MiB in full and skips any larger file entirely. Files over the recommended length (about 200 lines) trigger a startup and /status warning, and a second warning fires when many files and @ imports together pass a combined limit; that threshold scales with the model's context window. A paths list is capped at 1,000 brace-expanded patterns / 4 MiB, and patterns past the budget are used unexpanded.

The 200-line / 25KB truncation applies only to auto memory's MEMORY.md, not to CLAUDE.md.

Partly

There is no hard size limit or truncation of rule bodies; Cursor recommends keeping each rule under 500 lines and splitting larger ones. A rule's description is cut at 1,536 characters.

Every always-applied rule, AGENTS.md and CLAUDE.md uses context window on every request, so long files cost tokens.

There is no size limit or truncation. Each file is included whole.

There is no size limit. Each file is read in full and pasted into the system prompt without truncation, so very large files use up the model's context window.

Partly

Codex natively reads only AGENTS.md, which other harnesses also read. To reuse another tool's file, add it to project_doc_fallback_filenames (e.g. project_doc_fallback_filenames = ["CLAUDE.md"]); it is used only in directories without an AGENTS.md. /import can also make a one-time copy of CLAUDE.md into AGENTS.md, renaming Claude references to Codex.

/import writes only if the target AGENTS.md is missing or empty, and it doesn't keep the files in sync afterwards.

Yes. With the default Project instructions mode claude-md-or-agents-md, a repo with only AGENTS.md works as-is; set claude-md-and-agents-md to read both, or claude-md to ignore AGENTS.md. Set it in /config or in ~/.claude/settings.json / --settings / managed settings under pluginConfigs["cc-plugin-agents-md@builtin"].options.instructionFiles (ignored in project and local settings). Alternatively put @AGENTS.md in a CLAUDE.md, which works on any version and never double-loads.

Direct AGENTS.md reading needs v2.1.277+ and the built-in plugin enabled; before v2.1.281 it didn't work on Bedrock/Vertex/Foundry or with telemetry off. Before v2.1.285 the plugin ID was agents-md@builtin (still accepted).

Other tools' files such as .cursor/rules, .github/copilot-instructions.md or GEMINI.md aren't read at runtime; /init and /import copy them into CLAUDE.md once.

Yes. The CLI reads AGENTS.md, CLAUDE.md and CLAUDE.local.md alongside .cursor/rules, so one AGENTS.md or CLAUDE.md can serve Cursor, Codex, Claude Code and others. CLAUDE.md is always applied, ignoring any alwaysApply frontmatter. The CLI reads CLAUDE.md and CLAUDE.local.md only while its third-party configuration support is on, which is the default; AGENTS.md is always read.

Claude Code's @path imports inside CLAUDE.md are not expanded; Cursor treats them as plain text.

Partly

AGENTS.md is the shared convention and V2 reads it, so one AGENTS.md can serve OpenCode and other agents. V2 does not read CLAUDE.md or other tools' rule files; move that guidance into AGENTS.md.

Yes. Pi reads AGENTS.md, so a file written for Codex or other AGENTS.md tools works as is, and it falls back to CLAUDE.md in any directory that has no AGENTS.md. No setting is needed. If a directory has both, only AGENTS.md is used. Pi does not read ~/.claude/CLAUDE.md, .cursor/rules, GEMINI.md or similar files.

Pi also discovers skills in a project's .agents/skills directory, which other harnesses share. Skills are loaded on demand, not as instruction files.

Partly

The only scoping is by directory: put an AGENTS.md or AGENTS.override.md in a subdirectory and it applies when you start Codex in or below that directory. There are no globs, no frontmatter, and no @-mention rules that load on demand.

Files deeper than the working directory are not injected; the model is only told to look for them itself.

Yes: a .claude/rules/*.md file with YAML frontmatter paths: (a list or comma-separated globs, brace expansion allowed, e.g. src//*.{ts,tsx}) loads only when Claude reads, writes or edits a matching file; paths is the only frontmatter field read. There's no dedicated on-demand rule mechanism; you can @-mention a rule file in your prompt to attach it like any file, and the docs point to skills for instructions loaded only when asked for.

If the frontmatter YAML doesn't parse, the rule loads unconditionally; claude --debug shows the parse error.

Path-scoped rules that live in a symlinked directory outside the project don't load even after external imports are approved; only unscoped ones do.

Path-scoped rules are summarized away by compaction and reload on the next matching file access.

Yes. In a .mdc rule, alwaysApply: true applies it always; globs (comma-separated, e.g. src//*.tsx) attaches it when a matching file is in context; a description alone lets the agent pull it in when relevant; with none of these it applies only when you @-mention it (e.g. @my-rule). Team Rules can also carry glob patterns.

AGENTS.md and CLAUDE.md have no frontmatter scoping; use their directory placement instead.

Partly

There are no glob or frontmatter rules. A nested AGENTS.md effectively applies to its subtree because it is loaded only when the agent reads or lists something in that directory. Otherwise, reference a file in the prompt to pull it in on demand.

Not supported

No. Context files have no globs or frontmatter and always apply to Pi runs in their directory or below it. For guidance that should load only when it's relevant, write a skill: the model loads it on demand, or you can force it with /skill:name. Setting disable-model-invocation: true in a skill's frontmatter means it loads only when you call it explicitly.

Not supported

No. Codex inserts each file's text exactly as written, so @path or include lines are not expanded. You can still tell the model to read another file, and it will do so with its normal tools.

Yes: write @path/to/file anywhere in a CLAUDE.md or AGENTS.md (relative to the importing file, absolute, or @~/...); imported files load at launch and can import further, up to four hops deep. Escape spaces with \ ; imports inside code spans or fenced blocks are ignored. Imports in a project file that resolve outside the working directory need a one-time approval dialog; imports in user-scope files load without it.

Imports organize content but don't save context: imported files load in full at launch.

An external import inside a directly-read AGENTS.md loads only if external imports were already approved for the project, with no prompt.

Not supported

No. Writing @file.ts in a rule only tells the agent where to look; it reads the file with its tools when needed and the contents are never inlined. Put anything that must always be in context directly in the rule body.

Not supported

No. AGENTS.md content is sent as-is; @path references are not expanded, and the instructions config array that 1.x used for extra files is not applied in V2.

Not supported

No. Context files are inserted as plain text, so @path lines and links are not expanded. The model can still read a linked file with its tools if the instructions tell it to.

Set developer_instructions = "..." in ~/.codex/config.toml (or a profile) to add a separate developer message, or pass it for one run with -c developer_instructions='"..."'. model_instructions_file = "/abs/path.md" replaces Codex's built-in base instructions entirely, and OpenAI strongly discourages this. CODEX_HOME changes which global AGENTS.md is used; there is no flag or URL source for instruction files.

The older experimental_instructions_file key is gone in 0.162.1; use model_instructions_file.

Use --append-system-prompt "..." or --append-system-prompt-file <path> to add system-prompt-level text, or --system-prompt/--system-prompt-file to replace the default prompt. CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 with --add-dir <dir> loads that directory's CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md and CLAUDE.local.md, and admins can inline instructions with the managed-settings key claudeMd. URLs aren't supported as instruction sources.

--append-subagent-system-prompt(-file) adds text to subagent prompts in -p mode only.

In resumed conversations the recorded system prompt is reused; pass --system-prompt-snapshot off while iterating on appended text.

Partly

There is no flag or environment variable that injects instruction text. You can load extra rules with --plugin-dir <path>, which loads a local plugin whose rules/ folder holds .mdc rules, or by installing plugins from a marketplace; --workspace <path> chooses which project's rules load.

Partly

Not from config yet: the instructions array in opencode.json is accepted but its files, globs and URLs are not loaded. Clients can attach per-session instruction entries through the server API (PUT /api/experimental/session/{sessionID}/instructions/entries/{key}), and an agent's system field sets its own system prompt. There is no CLI flag.

--append-system-prompt <text|path> adds text or a file's contents and can be repeated; it replaces any discovered APPEND_SYSTEM.md for that run. --system-prompt <text|path> replaces Pi's base prompt, but context files are still added after it. Extensions can add or change prompt sections in a before_agent_start handler, and SDK users can add virtual context files with agentsFilesOverride. There is no settings key or environment variable for instruction text, and no way to load it from a URL.

Yes: /init in the TUI asks Codex to write a contributor-guide AGENTS.md ("Repository Guidelines") in the current directory. It won't overwrite an AGENTS.md that already exists there. /import can also create AGENTS.md from a Claude Code CLAUDE.md.

/init only asks the model to write the file, so the result varies; review it before committing.

/init analyzes the codebase and writes a starter CLAUDE.md, or suggests improvements if one exists; it also folds in .cursor/rules/.cursorrules and .github/copilot-instructions.md. With CLAUDE_CODE_NEW_INIT=1 it runs an interactive flow that can also set up CLAUDE.local.md (added to .gitignore), skills and hooks, and reads AGENTS.md, .windsurf/rules, .clinerules and .devin/rules. /import [codex|gemini|cursor] copies another agent's instruction files into CLAUDE.md, and /doctor prompt-audit audits existing instruction files.

/import needs v2.1.213+ (Cursor v2.1.265+) and isn't available on Bedrock, Vertex, Foundry or with feature-flag fetching off; /doctor prompt-audit needs v2.1.283+.

cursor-agent generate-rule (alias rule) asks for a description, a scope (project .cursor/rules/ or user ~/.cursor/rules/) and a name, then writes a starter <name>.mdc. In a session, /rules has a "Create new rule" entry where you pick the rule type and globs, and the built-in /create-rule skill has the agent write the rule for you. There is no /init that generates an AGENTS.md.

Yes. /init runs a guided setup that creates or improves AGENTS.md for the project; text after /init is passed as extra focus.

Not supported

There is no /init or similar command. Create AGENTS.md by hand, or ask Pi to write one with its file tools.

Run /status in the TUI; its Agents.md line lists the loaded files (e.g. ~/.codex/AGENTS.md, AGENTS.md). You can also ask Codex to list its instruction sources, or check the TUI log or session .jsonl. Edits to ~/.codex/AGENTS.md are picked up on the next turn, but project files are only re-read when the working directory or trust level changes (e.g. /cd). Otherwise restart Codex.

When instructions change mid-session, Codex sends the model a note that the new AGENTS.md text replaces the old one.

The docs say to restart Codex to pick up changes; there's no reload command.

Run /context and look under Memory files for what loaded at launch; /memory lists CLAUDE.md, CLAUDE.local.md and directly-read AGENTS.md paths (v2.1.280+) and opens them in your editor. On-demand files print a Loaded <path> line, and an InstructionsLoaded hook receives file_path, memory_type and load_reason (session_start, nested_traversal, path_glob_match, include, compact) for each CLAUDE.md or rule load. There's no dedicated reload command; /compact re-reads the project-root CLAUDE.md and unscoped rules from disk, and a new session picks up all edits.

InstructionsLoaded doesn't fire for an AGENTS.md read directly through the Project instructions setting, only for one imported by or symlinked from a CLAUDE.md.

Changing the Project instructions mode applies from your next message.

Partly

Run /rules in a session to browse, open and edit the .mdc files in the project's .cursor/rules/ and in ~/.cursor/rules/. It does not list AGENTS.md, CLAUDE.md or Team Rules, and there is no view of which rules were applied to a turn. Rule files are read when the CLI starts, so restart it to pick up edits; there is no reload command.

In the editor, Customize → Rules shows every rule and its status.

Partly

There is no command that prints the loaded files; each one appears in the model context as an Instructions from: <path> block, and clients can see which sources changed but not their contents. Edits to the global or upward AGENTS.md files are detected while a session runs and sent as an update (with a diff) before the next model request; edits to a nested file after it loaded need a new session.

The interactive startup header has a Context section listing every file loaded: SYSTEM.md, APPEND_SYSTEM.md, then the context files. It is hidden when quietStartup is true or "header", and --verbose shows it anyway. Edits are not picked up automatically; run /reload to re-read context files and update the system prompt in the current session.

Partly

There's no dedicated flag. -c project_doc_max_bytes=0 turns off all project AGENTS.md files for a run, and leaving a project untrusted also skips them. The global file still loads; to avoid it, point CODEX_HOME at another directory or remove/rename ~/.codex/AGENTS.md. You can't exclude individual files or directories.

--ignore-user-config skips config.toml but still loads ~/.codex/AGENTS.md.

To skip instruction files for a run, use --bare (or CLAUDE_CODE_SIMPLE=1), --safe-mode, or CLAUDE_CODE_DISABLE_CLAUDE_MDS=1; --setting-sources user drops project files and rules. To skip specific files, list absolute paths or globs in claudeMdExcludes in any settings file (arrays merge across layers), e.g. "claudeMdExcludes": ["/vendor//CLAUDE.md"]. Set instructionFiles to claude-md to ignore AGENTS.md, and set omitClaudeMd in a subagent definition to start that subagent without user, project and local CLAUDE.md.

claudeMdExcludes can't exclude the managed CLAUDE.md.

The built-in Explore and Plan subagents skip CLAUDE.md at startup.

Partly

There is no flag to skip instruction files for a run. To exclude a file, list an AGENTS.md or CLAUDE.md path in .cursorignore, or change a .mdc rule to manual (remove alwaysApply, globs and description). Non-enforced Team Rules can be turned off under Customize → Rules.

Partly

Set OPENCODE_DISABLE_PROJECT_CONFIG=1 (also read as OPENCODE_CONFIG_PROJECT_DISABLE) to skip project AGENTS.md discovery while keeping the global file. There is no switch for the global file and no exclude list.

Nested AGENTS.md files are still added when the agent reads files below the workspace.

Run pi --no-context-files (-nc) to skip every AGENTS.md/CLAUDE.md file for that run. You can't exclude a single file or directory, but adding an AGENTS.override.md to a directory replaces that directory's file. Project .pi/SYSTEM.md and .pi/APPEND_SYSTEM.md load only in trusted projects, so --no-approve (-na) skips them; context files load whether or not you trust the project.

--no-context-files does not affect SYSTEM.md or APPEND_SYSTEM.md.

Yes. Admins set additional_developer_instructions in requirements.toml (/etc/codex/requirements.toml, %ProgramData%\OpenAI\Codex\requirements.toml, cloud-managed requirements, or the macOS MDM key requirements_toml_base64). Codex adds it as its own developer message, separate from user files. Codex refuses to start if it exceeds about 10,000 estimated tokens. managed_config.toml can set defaults such as developer_instructions, but users can change those during a run.

Admins can't lock or block a repository's own AGENTS.md files; the managed text is added alongside them.

Partly

Admins can deploy a managed CLAUDE.md (macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux/WSL /etc/claude-code/CLAUDE.md, Windows C:\Program Files\ClaudeCode\CLAUDE.md) or set claudeMd in managed settings. It loads before user and project files and claudeMdExcludes can't exclude it. Managed settings can also set instructionFiles to managed-only, which leaves out user and project CLAUDE.md, rules and AGENTS.md at launch.

A user can still start with --safe-mode (or CLAUDE_CODE_SAFE_MODE=1), which skips managed CLAUDE.md along with other customizations.

Instructions are guidance, not enforcement; use managed permissions.deny, sandbox settings or hooks for hard limits.

In managed-only mode, subdirectory CLAUDE.md files and path-scoped rules still load on demand.

Yes, on Team and Enterprise plans. Admins create Team Rules in the dashboard and tick Enforce this rule so members cannot turn them off; enforced and enabled Team Rules apply to every repository, including CLI sessions. Admins can also mark a plugin that ships rules as Required so it cannot be uninstalled.

Non-enforced Team Rules can be switched off by each member in Customize.

Not supported

No. Managed config in /Library/Application Support/opencode, /etc/opencode or %ProgramData%\opencode and the macOS ai.opencode.managed profile can enforce settings and policies, but V2 ignores the instructions array and does not read an AGENTS.md from the system directory, so admins cannot push mandatory instructions.

Not supported

No. Pi has no managed or admin policy layer. Every instruction source is a user-editable file or a command-line flag, and any of them can be switched off with --no-context-files or replaced with --system-prompt.