Codex CLI
What do you lose when your agent can't import shared context?
Codex CLI reads
AGENTS.mdbut has no@-import syntax. The file must carry its own context. This is the trade-off: self-contained means portable but prone to drift.
Our Config
Codex walks from project root down to cwd, checking each directory for AGENTS.md. Files concatenate root-downward — closer files override earlier guidance.
AGENTS.md → self-contained rules (no imports)
~/.codex/AGENTS.md → global defaults
scripts/codex-hooks-check.sh → manual hook parity
AGENTS.md Structure
Because Codex has no import syntax, AGENTS.md inlines the core rules directly. This means it can drift from .ai/rules/ — the sync script mitigates this.
# Codex Project Rules (Mirror of .ai/)
## Intent
[Project description, platform model, key vocabulary]
## Operating Rules
[Inlined from .ai/rules/: content-standards, git-workflow, MDX patterns]
## Content Rules
[Inlined from .ai/rules/: page-flow, fact-and-star, content-quality]
## Frontend Rules
[Inlined from .ai/rules/: design-verification, design-checklist]
## Manual Hook Parity
[Instructions to run scripts/codex-hooks-check.sh]
Decision: Self-contained by necessity. Codex can't read @.ai/rules/content-standards.md. So the rules are inlined. The cost is drift — what AGENTS.md says may diverge from what .ai/rules/ says. A sync script regenerates AGENTS.md from .ai/ sources periodically.
What Codex Lacks
| Claude Has | Codex Equivalent | Gap |
|---|---|---|
@-imports | None | Rules must be inlined, causing drift |
| PostToolUse hooks | None | Validation is manual |
| PreToolUse build blocker | AGENTS.md text constraint | Soft instruction, not hard block |
/commands routing | Skills (experimental) | .agents/skills/*/SKILL.md |
| Auto-memory | None | No persistent learning across sessions |
| Always-loaded rules | AGENTS.md only | No .codex/rules/ directory |
Manual Hook Parity
Claude uses automated hooks in .ai/hooks/*.sh. Codex has no hook system, so a manual checker provides parity.
# After editing docs or src files:
pnpm run codex:hooks
# Or pass explicit files:
bash scripts/codex-hooks-check.sh docs/foo.mdx src/components/Bar.tsx
Decision: Accept the gap and bridge manually. Codex's value is as a second opinion and for teams already in the OpenAI ecosystem. The manual hooks catch the critical violations (MDX syntax, heading length, page flow) even without automation.
Drift Management
The sync script regenerates AGENTS.md from .ai/ sources:
# Rebuilds AGENTS.md from .ai/rules/ + .ai/CONTEXT.md
.ai/sync.sh
| Source | Section in AGENTS.md |
|---|---|
.ai/rules/content-standards.md | Content Rules |
.ai/rules/git-workflow.md | Build and Git Constraints |
.ai/rules/mdx-patterns.md | MDX Safety |
.ai/rules/design-verification.md | Frontend Rules |
.ai/rules/page-flow.md | Content Rules |
.ai/rules/fact-and-star-architecture.md | Content Rules |
Skills (Experimental)
Codex supports skills behind a flag:
codex --enable skills
Skills live in .agents/skills/*/SKILL.md or ~/.codex/skills/*/SKILL.md. This project's 13 skills are in .agents/skills/ with standard SKILL.md frontmatter — Codex discovers them natively.
Context
- Config Architecture — Agent-agnostic setup, decision log
- Claude Code — The deep-reasoning agent
- Gemini CLI — The broad-analysis agent
- AI Products — Higher-level product strategy
- Data Flow — Fuel for prediction models