# Context Management Across Codex Surfaces

URL: https://developertoolkit.ai/en/codex/build/context-patterns/
Description: Keep long Codex sessions on track: measure context with /status, control compaction, chain short threads with a handoff file, and move work across surfaces.

Context management in Codex means keeping a thread's fixed prefix (instructions, `AGENTS.md`, MCP tools, and skills) small and its conversation short enough that early constraints survive. Codex CLI 0.157.1 compacts history automatically and on `/compact`. The dependable pattern for long work is a chain of short threads joined by a handoff file, with tests as the check.

This page is for developers who run Codex on multi-hour tasks, and for tech leads who want those sessions to end the same way for everyone on the team. The situation is familiar: you are 40 turns into a billing migration, and Codex edits a v1 route you ruled out in turn 3, re-reads files it already summarised, and asks a question you answered an hour ago. The model did not get worse. The context it is working from did.

If you have not set up `config.toml` or MCP servers yet, start with [Codex configuration](/en/codex/quick-start/configuration/) and [MCP setup](/en/codex/quick-start/mcp-setup/).

## What a disciplined context setup in Codex gives you

- A way to measure what a thread carries before you blame the model: `/status`, `/mcp`, and `codex debug prompt-input`.
- A decision rule for when to compact, fork, side-chat, or start a new thread.
- A handoff file and two prompts that move a task between threads without re-planning it.
- A way to prove a long session still honours its constraints, without reading the transcript.
- Clear expectations for what crosses from the CLI to the desktop app, the IDE, and Codex cloud, and what does not.

## What fills a Codex thread's context?

Every turn sends the model one input. It has two parts, and they fail in different ways.

| Part | What is in it | How you see it | How you shrink it |
| --- | --- | --- | --- |
| **Fixed prefix**, paid on every turn | Codex's own instructions, your global `~/.codex/AGENTS.md`, the project `AGENTS.md` chain, skill names and descriptions, MCP tool definitions | `codex debug prompt-input "ping"` renders the instruction part as JSON; `/mcp` lists connected tools; `/skills` lists skills | [Trim the `AGENTS.md` chain and move procedures into skills](/en/codex/build/agents-md-optimization/); disable MCP servers a repository does not need |
| **Conversation**, grows every turn | Your prompts, the agent's replies, tool calls, command output, and file contents it read | `/status` shows token usage and the context window for the current model | `/compact`, `/side`, subagents, and new threads |

For the current OpenAI models, Codex uses a 272K-token window by default. You can raise it with `model_context_window` in `config.toml`, up to a catalog ceiling of 872K ([models hub](/en/ecosystem/models/) for the per-model details). A bigger window postpones compaction. It does not make the model attend equally to turn 3 and turn 300, and every turn re-sends everything that is still in the window. That is why this page treats the window as a budget to manage rather than a number to maximise.

**Measure your own prefix; do not trust a generic table**

The prefix depends on your `AGENTS.md` chain, the MCP servers you enabled, and your skills, so a fixed "tokens per component" table is wrong for your repository. Run `codex debug prompt-input "ping" > /tmp/prompt.json` from the directory you start Codex in, then check the file size. Run it again after you cut an `AGENTS.md` file or remove a skill, and compare. MCP tool definitions are not in this output (checked in Codex CLI 0.157.1); list them with `/mcp verbose` instead, and compare `/status` token usage with and without a server enabled. The command renders the prompt without sending it.

## Audit a thread before a long task

Do this once per repository, and again whenever someone adds an MCP server or a large `AGENTS.md`.

1. **Start a new thread** in the directory where you usually work, and run `/status`. Note the **Agents.md** line (which instruction files loaded, in order), **Token usage**, and **Context window**. Before the first turn there may be no usage to show, so send one short prompt (for example `ping`), then run `/status` again: the token usage after that first turn is roughly your prefix.

2. **List the tools.** Run `/mcp verbose`. Every connected server contributes tool definitions. A browser-automation server is dead weight in a database migration.

3. **Disable what this task does not need.** In `.codex/config.toml` for the project, or `~/.codex/config.toml` for you:

   ```toml
   [mcp_servers.playwright]
   enabled = false

   [mcp_servers.github]
   enabled_tools = ["get_pull_request", "list_pull_request_files"]
   ```

4. **Check the instruction chain.** If **Agents.md** is missing a file you expected, stop here and follow [how Codex decides which `AGENTS.md` files to load](/en/codex/build/agents-md-optimization/). The project chain shares a 32 KiB budget (`project_doc_max_bytes`, default 32,768 bytes), and Codex truncates the deepest file silently when the budget runs out.

5. **Re-run `/status`** in a new thread after the same short prompt, and confirm the token count dropped.

**Copy-paste prompt: audit the context this task needs**

```text
Before we start, audit your own context for this task: migrating the invoice API from the v1
router to v2 under services/api.
1. List the AGENTS.md files you loaded, in order, and quote the single rule from each that
   matters most for this task.
2. List the MCP servers and skills available to you and say which ones this task will
   actually use. Name the ones I can disable.
3. List the files you expect to read, grouped by directory, and estimate which are large
   (over 500 lines). For large files, name the functions you need instead of reading the
   whole file.
Do not edit anything. Keep the answer under 40 lines.
```

## When should you compact, fork, side-chat, or start a new thread?

Codex gives you several ways to stop a thread's history from growing. They are not interchangeable.

| You want to… | Use | What happens to context |
| --- | --- | --- |
| Keep going on the same task, but the thread is long | `/compact` | The conversation is replaced by a summary. Details you did not restate can be lost. |
| Ask a quick question without polluting the main thread | `/side` (alias `/btw`) | Starts a side conversation in an ephemeral fork. The main thread does not grow. |
| Try an alternative approach from the current point | `/fork` in the TUI, or `codex fork --last` | Copies the thread. Both copies carry the full history. |
| Start the next phase with a clean window | `/new`, then paste or reference the handoff file | Only what you pass across survives. |
| Let exploration happen elsewhere | Ask Codex to spawn a subagent (multi-agent is on by default in 0.157.1; `/subagents` switches between them) | The subagent reads files in its own thread and returns a report. |
| Continue yesterday's work | `codex resume --last`, or `codex resume <SESSION_ID or name>` | Reloads the saved thread, including everything that was in its context. |

The rule that follows: **compact within a phase, start a new thread between phases.** A phase is a unit you can verify on its own, for example "v2 router scaffolded and its contract tests pass". Compaction is a summary written by the model under pressure. A handoff file is a summary you wrote deliberately and can read.

### Tune when automatic compaction fires

Codex compacts on its own when a thread nears its limit. Two `config.toml` keys, both present in Codex CLI 0.157.1, change when:

```toml
# ~/.codex/config.toml
# Compact once the conversation reaches this many tokens, rather than near the full window.
model_auto_compact_token_limit = 180000

# Also compact after a final response once usage passes this percentage (0 to 100, checked in 0.157.1).
model_post_turn_compact_threshold_percent = 70
```

Leave both unset to keep Codex's built-in behaviour. Set them lower when you notice constraints slipping late in long threads. Earlier compaction produces smaller, more frequent summaries, and turns stay cheaper. Codex 0.157.1 also fires `PreCompact` and `PostCompact` hook events, which you can use to log when compaction happened in a session you are auditing.

Compaction is a fallback, not a plan. Codex 0.157.1 ships its own warning: "Long threads and multiple compactions can cause the model to be less accurate. Start a new thread when possible to keep threads small and targeted." The next section turns that advice into a routine.

## Chain short threads with a handoff file

The pattern that holds up over a multi-day task is a chain: one thread plans, and each later thread implements one phase from a file in the repository. The file is the only thing that crosses the boundary, so you can review it and version it.

1. **Plan in the first thread.** Ask for the phases, the files each phase touches, and the tests that prove each phase is done.

2. **Write the handoff to disk.** Have Codex write `docs/plans/invoice-v2.md` using the prompt below. Read it yourself; it is short by design. This is the one artifact in the chain you check line by line.

3. **Start each phase in a new thread** with `/new`, point it at the file, and name the thread with `/rename invoice-v2-phase-1` so `codex resume invoice-v2-phase-1` finds it later.

4. **End each phase by updating the file.** The thread records what changed, which decisions it made, and the test command that passed. The next thread starts from that state instead of rediscovering it.

**Copy-paste prompt: write the handoff file**

```text
We are ending this thread. Write docs/plans/invoice-v2.md as the handoff for the next thread.
Use exactly these sections:
1. Hard constraints (3-6 bullets that must never be violated, e.g. "do not modify v1 routes").
2. Decisions already made, with one line of reasoning each. The next thread must not reopen them.
3. Phases, each with: files it touches, the test command that proves it is done, and status
   (done / next / later).
4. Open questions that need a human answer.
Keep it under 60 lines. Do not include anything you have not verified in this thread.
```

**Copy-paste prompt: start the next phase from the handoff**

```text
Read docs/plans/invoice-v2.md. Treat its constraints and decisions as ground truth; do not
re-plan. Implement the phase marked "next" and nothing else. Before you edit, list the files you
will change. When you finish, run the phase's test command, paste the result, update the
phase status and the "Decisions" section in the file, and stop.
```

For scripted phases, `codex exec` supports the same chain. Choose deliberately between continuing a session and starting clean:

```bash
# terminal: continue the last exec session, carrying its whole transcript and its context cost
codex exec resume --last "Implement phase 2 from docs/plans/invoice-v2.md, then run its tests."

# terminal: start clean; only the handoff file crosses over
codex exec "Implement the phase marked next in docs/plans/invoice-v2.md, run its tests, update the file."
```

The clean start is the default for a new phase. Resume when the previous run was interrupted mid-phase and its tool output is still needed. For the interactive TUI, the equivalents are `codex resume --last` and `/new`. See [non-interactive Codex](/en/codex/automate/non-interactive/) for `--json`, `--output-schema`, and `--ephemeral` in pipelines.

## Keep exploration out of the main thread

The fastest way to fill a window is to let the implementing thread read the codebase. Two habits keep it lean.

- **Delegate the reading.** Ask a subagent to map the code and return a short report. The file contents stay in the subagent's thread. See [multi-agent workflows in Codex](/en/codex/automate/multi-agent-workflows/) for the patterns.
- **Ask for symbols, not files.** "Read `createInvoice` and its callers" costs a fraction of "read `services/api/src/`".

**Copy-paste prompt: explore with a subagent, keep the report small**

```text
Spawn a subagent to map how invoices are created in services/api. It should read whatever it
needs, then return only: the entry points (file:function), the call chain to the database
write, every place v1-only helpers are imported, and the existing tests that cover this path.
Max 30 lines, no code excerpts longer than 5 lines. Do not edit anything. When the report
arrives, summarise it in 5 bullets and wait for me.
```

## How do you prove a long session kept its constraints?

A long thread is where drift hides, and reading 300 turns to find it defeats the purpose of delegating. Put the proof in artifacts you can check in a minute.

- **Constraints as checks, not prose.** "Do not modify v1 routes" becomes a CI check that fails when a diff touches `src/routes/v1/`. A rule the agent can forget after compaction should be a rule the build enforces. As a CI step:

  ```bash
  git fetch origin main
  base=$(git merge-base origin/main HEAD) || exit 1
  changed=$(git diff --name-only "$base" HEAD) || exit 1
  if printf '%s\n' "$changed" | grep -q '^src/routes/v1/'; then
    echo 'v1 routes are frozen'; exit 1
  fi
  ```

  The step needs history back to the merge base, for example `fetch-depth: 0` on `actions/checkout`. On a shallow clone `git merge-base` fails, and the step fails with it instead of passing silently. On the `pull_request` trigger the workflow file comes from the pull request itself, so the same diff can delete the check: it holds only with `/.github/` in `CODEOWNERS` and code owner review required by branch protection or a ruleset.

- **A test command per phase** in the handoff file, run by the thread that finishes the phase and pasted into the file with its output.
- **Review in a fresh context.** Run `/review` in a new thread, or `codex exec review` from the terminal, after each phase. The reviewer has not seen the implementer's reasoning, so it judges the diff rather than the story. See [code review with Codex](/en/codex/ship/code-review/).
- **A diff scope check.** `/diff` at the end of a phase, compared with the file list in the handoff. A file outside the list is the first sign that the thread lost the plan.
- **A record.** `/export` saves the conversation as Markdown. Keep it next to the pull request when a reviewer needs to trace a decision, instead of pasting transcripts into chat.

The tech lead signs off on the handoff file and the CI result; nobody signs off on the transcript.

## What crosses between Codex surfaces?

The CLI, IDE extension, desktop app, and Codex cloud share configuration and instructions in some directions only. Plan for what does not travel.

| From → to | What travels | What does not |
| --- | --- | --- |
| CLI → desktop app | `/app` continues the current session in the desktop app (macOS and Windows only; the Linux CLI has no `/app`) | Not available from Linux. On macOS and Windows nothing is lost, but confirm the app opened the same thread |
| IDE → CLI | `/ide` pulls the current selection, open files, and other context from your IDE into the TUI | Anything you did not select or open |
| Local → Codex cloud | What is committed to the repository, including the `AGENTS.md` files | Your `~/.codex/` config and global `AGENTS.md`, uncommitted files, and your local handoff notes |
| One thread → another | The handoff file, if committed or on disk | Thread history; `memories` is off by default in 0.157.1, so do not expect Codex to remember across threads |

The cloud row causes the most surprises. A cloud task sees the repository, not your laptop. Commit the handoff file and any `AGENTS.md` rule the task depends on before you delegate. See [Codex cloud environments](/en/codex/automate/cloud-environments/) for setup scripts and environment variables.

## What breaks when a Codex thread runs out of room?

- **A constraint from early in the thread is ignored.** Compaction summarised it away. Restate it in the current prompt now, then move it into the handoff file and, if you can, into a CI check. Lower `model_auto_compact_token_limit` if this recurs.
- **Turns get slow and the thread keeps re-reading files.** The window is near full and each turn re-sends it. Write the handoff file and continue in a new thread; do not `/compact` a third time.
- **A module's `AGENTS.md` rules stopped applying.** The project chain passed its 32 KiB budget and the deepest file was truncated, or an `AGENTS.override.md` is hiding it. Check the **Agents.md** line in `/status`, then follow [the budget fixes](/en/codex/build/agents-md-optimization/).
- **No project instructions load at all.** Since 0.150.0, an untrusted project supplies no project-level `AGENTS.md`. Trust the project when Codex asks, or check its `[projects."<path>"]` entry in `~/.codex/config.toml`.
- **A resumed thread is already near its limit.** `codex resume` reloads everything the thread held. Resume only to finish an interrupted phase; start the next phase with `/new` and the handoff file.
- **A cloud task ignores a convention you rely on locally.** The rule lives in `~/.codex/AGENTS.md` or an uncommitted file. Commit it to the repository's `AGENTS.md`.
- **Raising `model_context_window` did not help.** A larger window delays compaction but every turn costs more. Cut the prefix and shorten the threads first; see [cost management](/en/codex/operate/cost-management/) for how usage adds up.

## Where to go next with Codex context

- [Optimize `AGENTS.md` and skills for Codex](/en/codex/build/agents-md-optimization/): the budget, load order, and truncation rules behind the fixed prefix.
- [Prompt engineering for Codex](/en/codex/build/prompt-engineering/): prompts that state constraints once and precisely.
- [Multi-agent workflows](/en/codex/automate/multi-agent-workflows/): split work so that no single thread carries it all.
- [Build: plan.md, then implement](/en/method/lifecycle/build/): the tool-neutral version of the handoff-file chain.
- [Efficiency hacks](/en/codex/build/efficiency-hacks/): shortcuts for resuming, forking, and moving between surfaces.