Codex (codex)
Set up this tool
Config keys
Codex config
Keys codex ignores in a project config
Codex exec policies
Translate bash permissions
Import
Write project instructions and rules under .agnostic-ai/. Sync gives Codex AGENTS.md, native skill folders, and any configured agents, hooks, MCP servers, or settings. The same sources can also feed Claude Code.
Using this provider through Composer? Follow the Composer setup guide.
First rule
Install the client using the official setup guide, then open your project in it.
Select codex in agnostic-ai.yaml, then follow First rule. The shared commit-prefix rule becomes a section in root AGENTS.md. With Claude Code also selected, the same source becomes .claude/rules/conventional-commits.md.
Write shared project instructions in .agnostic-ai/AGNOSTIC_AI.md. Sync combines them with the Codex rules in AGENTS.md. Edit those sources for later changes.
Already configured? Check import coverage before syncing. Import reads root and nested instruction files, agents, skill folders, hooks, MCP servers, environments, and remaining project config into an overlay.
Output
| Source | Default output |
|---|---|
| Instructions and project-wide rules | AGENTS.md |
| Directory-scoped rules | <scope>/AGENTS.md |
| Skills and bundled files | .agents/skills/<name>/SKILL.md |
| Commands | .agents/skills/<name>/SKILL.md, as skills the user runs by name |
| Agents | .codex/agents/<name>.toml |
| Hooks | .codex/hooks.json, when configured |
| Settings and MCP servers | .codex/config.toml, when configured |
| App environment | .codex/environments/environment.toml, when configured |
| Exec policies | .codex/rules/default.rules, opt-in |
An empty kind creates no corresponding files. Prefer skills for prompt procedures: project custom-prompt output is a deprecated compatibility option that Codex does not discover. With outputs.codex.commands-dir set, commands go there instead of becoming skills. See output overrides.
Loading and limits
- Codex discovers instructions from the project root to the session's working directory. Start inside a subtree to load its nested
AGENTS.md; editing there from a root-started session does not load it. Start a new session after changing instructions. - Command and MCP-tool hooks require trust through
/hooks, including after their configuration changes. Project hooks also need a trusted project.agnostic-ai doctor -t codexchecks saved trust, not whether an already-running session bypasses it. - Agents inherit the session sandbox. Codex v0.155.0 and later ignore an agent's
sandbox_mode, soreadonly: truedoes not enforce read-only behavior there. Use session limits and exec policies.
Codex project config takes precedence over user config in a trusted project. Keep user-level keys in the home configuration, and use the Codex native reference for supported project fields and overlay precedence.
Protected paths
A settings spec's protected block creates an apply_patch hook and .codex/hooks/agnostic-ai-protect.sh. It checks added, edited, deleted, and moved paths in a patch. decision: ask blocks and tells the agent to ask you; the hook cannot open an approval prompt.
The guard needs trusted hooks, sh, and awk. It does not see shell commands that write files. On Windows, if sh is missing, the hook cannot start and the edit goes through. See protected paths.
Verify
Run agnostic-ai sync --check and inspect root AGENTS.md for the commit-prefix rule. Start Codex from the project root and ask for a commit subject for a small fix; it should use fix:.
For a scoped rule, start a new session inside its directory. agnostic-ai explain --file services/api/handler.go --target codex reports planned instruction files and discovery limits; it does not confirm the files loaded in a running session.
Next, add a reusable skill or compare the same setup in Claude Code.