Codex CLI

What do you lose when your agent can't import shared context?

https://openai.com/codex/

Codex CLI reads AGENTS.md but 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 the shared rules directory — 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 import a shared content-standards rule file, so the rules are inlined. The cost is drift — what AGENTS.md says may diverge from what the shared rules source says. A sync script regenerates AGENTS.md from those 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)	Skill definition files
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 rule	Section in AGENTS.md
content-standards	Content Rules
git-workflow	Build and Git Constraints
mdx-patterns	MDX Safety
design-verification	Frontend Rules
page-flow	Content Rules
fact-and-star	Content Rules

Skills (Experimental)

Codex supports skills behind a flag:

codex --enable skills

Skills live in per-skill definition files under a skills directory, either project-local or user-global. This project's skills sit in the project skills directory with standard frontmatter — Codex discovers them natively.

When To Use

Use Codex when you want a second-opinion agent or your team already runs in the OpenAI ecosystem. Reach for an import-based agent instead when config drift is the bigger risk than portability. Example: a fast-moving repo with many rule files favours imports; a portable single-file setup favours Codex.

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

Signal

Changes my mind: show a self-contained config that stays in sync with its sources indefinitely, with no regeneration script. Then the drift trade-off vanishes and the case for import-based agents weakens.

Next question: at what number of rule files does manual sync cost more than adopting an import-capable agent?

Questions

Which engineering decision related to this topic has the highest switching cost once made — and how do you make it well with incomplete information?

• At what scale or complexity level does the right answer to this topic change significantly?
• How does the introduction of AI-native workflows change the conventional wisdom about this technology?
• Which anti-pattern in this area is most commonly introduced by developers who know enough to be dangerous but not enough to know what they don't know?