# Codex CLI Implementation

> OpenAI's Codex CLI implementation patterns including directory-walk concatenation, model tier assignment, and profile configuration

- **Category**: optimizing-token-usage-practices

- **Canonical URL**: https://designpattern.fyi/optimizing-token-usage-practices/part-ii-codex-cli/

---

## Description
OpenAI's Codex CLI implementation patterns including directory-walk concatenation, model tier assignment, and profile configuration








## Additional Notes

## 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