# Codex usage-efficiency handoff

Portable setup for cutting Codex (GPT-6 Astra) usage by roughly half without giving up the
strong model for thinking. Measured on a heavy multi-project account over two days
(5,782 model calls): 60% of spend was the same context being replayed on every tool call,
23% was fresh input, 16% was output including reasoning. So the levers are **context size**,
**call count**, and **which model does the grunt work**, not thinking depth.

Copy the three pieces below. Nothing here needs any secret.

---

## 1. `~/.codex/config.toml`

Keep Astra as the main model. Add or change these keys:

```toml
model = "gpt-6-astra"
model_reasoning_effort = "high"          # was "max"; high keeps judgment quality

# Compact the thread before it balloons. Every call replays the whole context,
# so a 200K thread costs ~2x a 100K thread per call.
model_auto_compact_token_limit = 100000

# Spawned workers default to the cheap model.
[agents]
default_subagent_model = "gpt-5.6-terra"
default_subagent_reasoning_effort = "medium"
max_concurrent_threads_per_session = 4
```

Optional extras if you want more: `mcp_servers.<id>.enabled = false` for any MCP server you are
not using that day (each one adds its tool list to every call), and nesting long project
`AGENTS.md` files so only the relevant section loads.

## 2. Two custom agents in `~/.codex/agents/`

`~/.codex/agents/collector.toml`

```toml
name = "collector"
description = "Cheap read-and-capture worker. Use for screenshots, page captures, API/data pulls, file and log reads, and research sweeps. Returns a compact summary plus artifact paths; never makes judgment calls or edits."
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
developer_instructions = """
You collect evidence for a parent agent that does the thinking.
Do exactly the capture or read requested. Batch shell commands into as few calls as possible.
Take one screenshot per requested view; never re-take or re-attach images unless the parent asks.
Save artifacts to the paths the parent names and return: what was captured, exact file paths, key numbers or quotes, and anything that failed.
Do not analyse, rank, recommend, or edit project files.
Keep the summary under 40 lines.
"""
```

`~/.codex/agents/builder.toml`

```toml
name = "builder"
description = "Execution worker for scripted, well-specified work: code edits, renders, builds, uploads, bookkeeping. Use after the parent has decided what to build."
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
developer_instructions = """
You implement decisions the parent agent has already made. Follow the repository AGENTS.md and any named skill exactly.
Make the smallest change that satisfies the spec; do not redesign, re-scope, or improve adjacent code.
Batch shell commands. Verify with the repository's own checks and report the exact commands and results, including failures.
Return changed file paths, verification output, and open blockers in under 40 lines.
"""
```

## 3. Rules in `~/.codex/AGENTS.md`

Paste this section into your global `AGENTS.md` (create the file if it does not exist):

```markdown
# Token discipline

The main thread stays on GPT-6 Astra at high reasoning for interpreting the operator, analysis,
creative and copy judgment, ranking, and final review. Everything mechanical goes to the custom
agents in `~/.codex/agents/`:

- `collector` (Terra): screenshots, page captures, data pulls, file and log reads, research sweeps.
  It returns paths and a short summary, never a judgment.
- `builder` (Sol): scripted code edits, renders, builds, uploads, bookkeeping, once the decision
  is made.

The main thread does not run shell commands, read large files, or take screenshots itself when a
worker can do it. Delegate by naming the agent, give it a bounded brief, and ask for a summary
under 40 lines. Never pull a worker's raw tool output into the main thread.

Batch shell commands into one call whenever they do not depend on each other. Take one screenshot
per verification point, not per iteration, and never re-attach an image already in the thread.
Read only the files the task needs; do not re-read instruction or handoff files mid-thread unless
they changed.

Start a new thread at every phase boundary (research → build → QA → publish) and whenever
`/status` shows context above roughly 120K tokens. Close out with a short checkpoint (goal,
current state, exact artifact paths, decisions, blockers, next action) and seed the new thread
from that checkpoint plus the two or three named files, never from the transcript. Prefer a fresh
thread over `/compact`.
```

## 4. Restart and verify

Quit and reopen the Codex app (or `codex app-server daemon restart` on a headless box). Existing
threads keep the old settings; new threads pick up everything.

Open a new thread, type `/status`, then paste:

```
Confirm my usage settings without doing any other work:
1. Which model and reasoning effort is this thread running?
2. Read ~/.codex/config.toml and report model, model_reasoning_effort, model_auto_compact_token_limit and the [agents] block.
3. List ~/.codex/agents/ and report each agent's name and model.
4. Confirm ~/.codex/AGENTS.md contains a "Token discipline" section.
Answer in a short table. Do not change anything.
```

Expected: Astra high; compact limit 100000; subagent default Terra medium; collector on Terra,
builder on Sol; section present.

## 5. What to expect

| Change | Saving on its own |
|---|---|
| Compact / new thread around 100K | ~25% |
| Batching, fewer screenshots | ~10% |
| High instead of max reasoning | ~3% |
| Workers on Terra/Sol instead of Astra | 20 to 30% more, depending on how much you delegate |

Combined, expect roughly half to two thirds off per unit of work. Your hourly burn will only
drop if you also run fewer threads in parallel; each main thread plus its workers is its own
budget line.

## 6. Habits that matter more than settings

- One job per thread. New phase, new thread.
- Say what you want checked, not how. Let workers fetch; let Astra judge.
- Do not paste transcripts or old screenshots into a new thread. Paste the checkpoint.
- Check `chatgpt.com/codex/settings/usage` weekly to see the pace.