Codex CLI workflows · AI coding agents

Mini-workflows using verified Codex commands. Cross-tool, tool-agnostic versions of these workflows live in Example: Understand a new repository (and the other walkthroughs such as Example: Build a new feature end to end); for capability comparisons across agents see Feature Matrix.

Understand a codebase

codex --sandbox read-only --ask-for-approval on-request

> /init                          # scaffold AGENTS.md so future sessions know the repo
> Explain the request lifecycle in this repo, from HTTP entry to database
> /mention src/server.ts
> Where is authentication enforced? List file:line references

Tips: read-only sandbox keeps exploration side-effect-free; @ attaches files; /status confirms the active model and writable roots. For large repos, ask Codex to delegate exploration to explorer subagents (see Codex CLI subagents).

Build a feature

codex --sandbox workspace-write --ask-for-approval on-request   # the recommended "Auto" combo

> /plan Propose an implementation plan for adding retry-with-backoff to the payment client
> (approve the plan, then:) Implement it, with tests
> /diff                          # inspect exactly what changed, including new files

Tips: /plan gets you an approach to approve before edits; a good AGENTS.md (build/test commands, style rules) pays off here; /compact when the session gets long; /goal for multi-step objectives with automatic continuation.

Debug

codex --sandbox workspace-write --ask-for-approval on-request

> Tests are failing with "connection refused" in src/db/pool.test.ts — find the cause and fix it
> ! npm test -- --run pool      # run a local command under the current sandbox yourself
> /ps                            # check background terminals; /stop kills them

Non-interactive alternative for CI logs:

cat failure.log | codex exec --sandbox read-only "Find the root cause in this log" -

Refactor

> /new refactor-session
> /plan Propose a stepwise refactor of the config module into typed submodules
> Implement step 1 only
> /diff

Tips: work in small, verifiable steps; use /fork to try an alternative approach without losing the current transcript; use /new to keep refactors out of unrelated chats. For sweeping renames across a monorepo, subdirectory AGENTS.md files keep per-package conventions in scope (see Codex CLI project instructions (AGENTS.md)).

Code review

Interactive, before committing:

> /review                        # reviews the working tree; never modifies it

Non-interactive, for branches, commits, or automation:

codex review --uncommitted                    # staged + unstaged + untracked
codex review --base main                      # diff against a branch
codex review --commit abc123 --title "hotfix"
codex review "Focus on SQL injection risks"   # custom prompt instead of a target
echo "Focus on SQL injection risks" | codex review -   # custom prompt from stdin

Notes: set review_model in config.toml to use a different model for reviews; codex apply <TASK_ID> pulls the diff from a Codex cloud chat into your local tree.

Last verified: 2026-09-07

Official sources:

AI coding tools evolve quickly. If you find outdated information, please open an issue or pull request.