How Codex CLI works
A mental model of the interactive agent, repository context, configuration layers, tools, and verification loop.
Codex CLI is a coding agent that works inside a terminal. It can inspect a repository, edit files, run commands, and report the result while operating within explicit filesystem, network, and approval boundaries.
The useful way to think about it is not “a chatbot that writes code,” but a repository-aware work loop: understand the goal, gather context, plan when needed, make a bounded change, run checks, and review the result.
Interactive and non-interactive modes
Running codex opens the interactive terminal interface. This mode is suited to
work that benefits from discussion, steering, and review. You can refine the goal
while the agent is working, inspect its diff, adjust permissions, or continue a
saved session.
codex exec runs a task non-interactively. It is designed for scripts, CI jobs,
scheduled checks, and pipelines. Progress goes to standard error while the final
agent message goes to standard output, making the result easy to redirect or
pipe. JSON Lines output is available when a machine needs every event rather than
only the final answer.
These modes share the same agent and configuration system, but they serve
different workflows. Use the interactive interface for collaboration; use
codex exec when inputs, permissions, and expected output are already clear.
Context comes from several layers
Codex combines your prompt with the repository, configuration, and durable
instructions. The most important project instruction file is AGENTS.md. It can
describe the repo layout, build commands, conventions, constraints, and the
checks required before work is complete.
Instruction files can be placed at several directory levels. More specific guidance closer to the current working directory takes precedence over broader guidance. This lets a monorepo keep shared rules at the root and local commands inside individual packages.
Configuration follows a similar layered model. One-off CLI flags have the highest priority, followed by trusted project configuration, an optional named profile, personal configuration, system configuration, and built-in defaults.
Tools operate inside a boundary
The model does not receive unrestricted computer access. A sandbox controls what commands can technically read, write, or reach over the network. An approval policy separately controls when Codex pauses for human permission.
This separation is important. A permissive approval setting does not add access that the sandbox forbids, and a writable sandbox does not imply that every risky action should happen without confirmation.
The verification loop matters
Codex can produce plausible code quickly, so the last phase is essential. Give it the commands that define a successful change: tests, formatting, type checking, builds, or a focused reproduction. Review the diff and ask for a second pass when the risk justifies it.
The agent becomes more reliable when “done” is an observable repository state, not merely a completed response.