# How Codex works

Codex CLI runs the agent loop in your terminal with shell and apply_patch tools, a sandbox plus approval policy, and config layers in config.toml.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/how-coding-agents-work/codex

This page covers the Codex CLI in your terminal. Codex also runs in a desktop app, an IDE extension and the cloud, with the same configuration layers.

## At a glance

| | Codex CLI |
|---|---|
| Term | Codex CLI (`codex`): the interactive terminal UI; `codex exec` for scripts |
| Configured in | `~/.codex/config.toml` (user), `<repo>/.codex/config.toml` (project), `/etc/codex/config.toml` (system, Unix) |
| Runs | A turn starts when you submit a prompt and ends with the model's final message |
| Scope & precedence | CLI flags and `-c` overrides > project files (closest wins, trusted projects only) > `--profile` file > user > cloud-managed > system > built-in defaults |

## Build the scenario

Start Codex in a new Git repository and send the prompt from the [example scenario](https://ai-sw-factory.mellicci.dev/fundamentals/how-coding-agents-work/example-scenario):

```bash
mkdir hello && cd hello && git init
codex
```

| Turn | What Codex decides | Tool | Prompt in the `Auto` preset |
|---|---|---|---|
| 1 | Write `hello.py` | `apply_patch` | None: edits inside the workspace are allowed |
| 2 | Run it | shell (`python3 hello.py`) | None: the sandbox allows it; network access would ask |
| 3 | Report the output | None, plain text | None |

If `python` is missing, the error is fed back and Codex tries another command. Afterwards, `/status` shows the model, approval policy, writable roots and token usage, and `/diff` shows what changed.

The same task without the TUI:

```bash
codex exec --sandbox workspace-write "Create a hello world app in Python and run it."
```

Progress streams to `stderr`; only the final message goes to `stdout`. Without `--sandbox workspace-write`, `codex exec` runs read-only and cannot create the file.

## Specifics

### Tools

| Tool | What the model asks for | Note |
|---|---|---|
| Shell (`shell` / unified exec `exec_command`) | Run a command | Runs under the sandbox and approval policy; feature flags `shell_tool` and `unified_exec` default to on (`unified_exec` except on Windows) |
| `apply_patch` | Edit or create files | Hooks match it as `apply_patch`, `Edit` or `Write` |
| MCP tools | Tools from servers you add with `codex mcp` | Listed with `/mcp` |
| Web search | Look up current information | Hosted tool; cached results by default, `--search` for live |
| `update_plan`, subagent tools | Plan steps, delegate work | `/agent` switches between agent threads |

The documentation doesn't publish a complete tool list; the names above are those it mentions.

### Models and reasoning effort

| How | Command or setting |
|---|---|
| Launch with a model | `codex --model <name>` or `-m`; also works with `codex exec -m` |
| Switch mid-session | `/model`: pick a model, then reasoning effort (choose **More reasoning...** for Max or Ultra where supported) |
| Default in config | `model = "..."` and `model_reasoning_effort = "medium"` in `config.toml` |
| Fast service tier | `/fast`, when the current model offers one |

Higher effort can improve hard tasks but takes longer and uses more tokens. The available models depend on your account and plan; `/model` shows only those.

### Context and compaction

| Need | What to use |
|---|---|
| See context usage | `/status`, or a footer item via `/statusline` |
| Summarize earlier turns | `/compact` replaces earlier turns with a summary |
| Automatic compaction | Happens near the limit; `model_auto_compact_token_limit` in `config.toml` sets the threshold (unset uses model defaults) |
| Start fresh | `/clear` resets the screen and the chat context |
| Add files | Type `@` to search for a path, or `/mention` |

### Sessions

| Command | Does |
|---|---|
| `codex resume` | Reopen a saved chat; `--last` picks the most recent one in the current directory, `--all` searches everywhere |
| `codex fork` / `/fork` | Copy a session into a new chat |
| `codex exec resume --last "<prompt>"` | Continue a non-interactive run |
| `codex archive`, `codex delete` | Hide or permanently remove a saved session |

### Permissions at a glance

Two controls work together: the **sandbox** limits what commands can touch, **approvals** decide when Codex stops to ask. Change them mid-session with `/permissions`. Depth: [security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model) and [sandboxing](https://ai-sw-factory.mellicci.dev/fundamentals/sandboxing).

| Preset | Sandbox + approval | Behavior |
|---|---|---|
| Read Only | `read-only` + `on-request` | Reads and plans; asks before edits |
| Auto | `workspace-write` + `on-request` | Edits and commands in the workspace run freely; asks to leave it or use the network |
| (no preset) | `--sandbox danger-full-access` | No sandbox; the docs advise it only in a controlled environment |

### Interactive vs non-interactive

| | `codex` | `codex exec` |
|---|---|---|
| Output | TUI | Progress on `stderr`, final message on `stdout`; `--json` for JSONL events |
| Default sandbox | Depends on folder trust (see below) | Read-only |
| Approvals | Asked in the TUI | Set by flags; no human to ask |

See [headless execution](https://ai-sw-factory.mellicci.dev/fundamentals/headless-execution) for the concept.

### Undo

The documentation describes no undo command. It recommends Git checkpoints before and after a task so you can revert, and `/diff` to review edits.

## Gotchas

- **Folder type changes the default.** In a Git repository Codex recommends `Auto`; in a folder that is not version controlled it recommends `read-only`, and it may start read-only until you trust the directory. Run `git init` first, or switch with `/permissions`.
- **`codex exec` is read-only and needs Git.** It cannot edit files without `--sandbox workspace-write`, and it refuses to run outside a Git repository unless you pass `--skip-git-repo-check`.
- **No network in the sandbox.** Installing a dependency needs approval or `sandbox_workspace_write.network_access = true`.
- **Project config loads only when trusted.** An untrusted project skips its `.codex/` config, hooks and rules; user and system layers still load.
- **`/compact` is lossy.** Earlier turns become a summary, so restate a constraint that still matters.