Codex CLI Implementation

Codex CLI Token Optimization

Layer 1 — Platform Mechanics

AGENTS.md is native; use the directory-walk concatenation deliberately — universal rules at the project root, narrower rules in nested AGENTS.md files closer to the code they govern (Codex concatenates root-down, so nested files add rather than replace). Give read-only/mapping subagents a cheaper model tier (OpenAI’s own example pairs a code_mapper subagent with a mini-tier model and a read-only sandbox) and reserve the full model for the agent that edits code. Set model_reasoning_effort to low/minimal by default — xhigh costs 3–5x more tokens and should be reserved for genuinely hard problems.

Key Strategies:

• Directory-Walk Concatenation: Leverage hierarchical AGENTS.md structure
  • Universal rules at project root
  • Narrower rules in nested directories
  • Codex concatenates root-down (adds, doesn’t replace)
• Tiered Subagent Models: Assign model tiers by subagent role
  • Read-only/mapping subagents: Mini-tier models
  • Code editing agents: Full model tier
  • Example: code_mapper with mini-tier + read-only sandbox
• Reasoning Effort Control: Default to low/minimal
  • xhigh costs 3–5x more tokens
  • Reserve for genuinely hard problems only

Layer 2 — Agent Operation

Tune model_auto_compact_token_limit rather than accepting the default. Use codex exec for scripted/CI runs to skip TUI overhead. Keep a lean --profile (cheap model, low effort, read-only sandbox) separate from your interactive daily-driver profile.

Operational Best Practices:

• Auto-Compact Tuning: Adjust model_auto_compact_token_limit from default
• CI/Scripted Runs: Use codex exec to skip TUI overhead
• Profile Separation: Maintain distinct profiles
  • Lean profile: Cheap model, low effort, read-only sandbox
  • Interactive profile: Full model for daily development
• Batch Operations: Group related operations to reduce session overhead

Layer 3 — Codebase Architecture

Same AGENTS.md Conventions section, whether at repo root or nested per-package.

Architecture Rules:

• Shared Conventions: Maintain consistent AGENTS.md Conventions section
• Nested Structure: Use nested AGENTS.md for package-specific rules
• Concatenation Order: Rules concatenate root-down, earlier rules win

Codex CLI-Specific Features

Plan Mode Configuration

Codex CLI uses plan_mode_reasoning_effort config key to control planning behavior:

• Set appropriate reasoning effort for planning phase
• Separate planning from execution to control costs
• Use lower effort for initial planning, higher for implementation

Skills Configuration

Codex CLI uses [[skills.config]] for per-skill enable/disable:

• Fine-grained control over which skills load
• Reduce token overhead by disabling unused skills
• Profile-specific skill configurations

Subagent Definitions

Subagent definitions in ~/.codex/agents/*.toml or .codex/agents/*.toml:

• Each subagent has independent model/reasoning effort/sandbox
• Support for complex multi-agent workflows
• Isolated contexts for parallel execution

Profile System

Codex CLI’s profile system allows environment-specific configurations:

• Development profile: Full capabilities
• CI profile: Lean, automated, cost-optimized
• Review profile: Read-only, cheap model tier