Skip to content

Codex CLI Practical Best Practices — Usage Essentials & FAQ

Codex CLI Complete Guide

This page complements the existing best‑practices with practical guidance on AGENTS.md, model selection, context/tokens, the UI percentage indicator, and cost control.

1) AGENTS.md and customization

  • Auto‑generation: In this repo AGENTS.md is not auto‑generated. If you automate it, document the source, timing, and script entry points in the README and PR.
  • Edit scope: Prefer minimal updates focusing on policy/priorities/constraints. Day‑to‑day behavior can be driven via preambles and update_plan.
  • Secrets & responsibilities: Never put secrets. Write down escalation/destructive‑action rules and keep roles/boundaries concise.
  • How far to customize: Run with defaults first. Add targeted rules only where repeated pain appears. Template or script once stable.

2) Picking a model

  • Principle: Balance difficulty × cost × length.
  • Hard design/refactor/bug‑hunt: strongest reasoning model available to you
  • Broad reads/summary/mechanical work: cost‑efficient small/mini models
  • Long diff or long context tasks: models with larger context windows
  • When to switch: Fix the model per phase (design → implement → verify) for consistency and reproducibility.
  • Repro: Record model, temperature, and conditions for important tasks in Issues/PRs.

3) Context/token management tips

  • Narrow reads: use rg to locate snippets and read in ≤250‑line chunks. Avoid pasting entire files.
  • Summarize as scaffolding: capture “assumptions/decisions/open items” in a few lines and reuse them in later turns.
  • Minimal diffs: keep apply_patch focused on one topic per task.
  • Refer by path: prefer path:line pointers over large code pastes.
  • Tame logs: include only the decisive parts of build/test logs.

4) Percentage indicator (why it decreases)

  • What it reflects: a combined “resource usage” signal (primarily tokens, also tool I/O). Long inputs/outputs drain it faster.
  • What happens near limits: truncation, tool throttling, or forced summarization; answers may become coarse or omit details.
  • How to manage it:
  • Stage reads and pass forward short summaries
  • Avoid full logs and whole‑file pastes
  • Verify changes locally first, then expand scope

5) Cost optimization

  • Split tasks: reserve strong models for hard reasoning; offload repetitive discovery to small models and local search.
  • Lock the plan first: agree on update_plan to cut wasted iterations.
  • Verify near the change: validate locally, then expand as confidence grows.
  • Cache thinking: keep short notes of structure/decisions to avoid re‑feeding long context.

6) Quick FAQ

Q1. Is AGENTS.md auto‑generated every run? No. It’s manual in this repo. If you automate, document the source, schedule, and add the script.

Q2. Should I heavily customize prompts? Start with defaults; add minimal targeted rules only where needed. Clear preambles plus update_plan usually outperform monolithic prompts.

Q3. Which model should I use? Strong model for “hard reasoning & critical decisions”; small model for broad reads/summary/mechanical tasks. Fix the choice per phase.

Q4. What does the percentage in the UI mean? Approximate resource usage in the conversation (mostly tokens). It drops faster with long I/O. Stage reads, summarize, and keep diffs minimal.

Q5. Running out of tokens — what helps? - Use rg to target snippets and read ≤250 lines - Carry forward short summaries between turns - Keep patches small and focused - Avoid full logs/whole‑file pastes

7) Repo validation checklist

  • Strict build: mkdocs build --strict
  • Pair check: run the JP/EN article pair validation script
  • Optional redirects: run the redirect verification script (needs auth + network)