Performance optimization with Codex

Performance optimization with Codex is a four-stage loop: a read-only diagnosis that names the bottleneck, a benchmark harness committed before any fix, best-of-N cloud tasks (codex cloud exec --attempts, up to four) that try competing strategies, and a deterministic gate that accepts a change only when the team’s own benchmark and test suite both pass.

This guide is for developers who own a slow service and tech leads who decide when a performance change can merge. Your API’s p95 latency crossed two seconds, the dashboard is red, and the slow request touches three services, a database, and a cache. Your laptop database holds one thousandth of production’s rows, so a local profile points at the wrong code. Commands on this page were checked against Codex CLI 0.157.1 on 2026-09-26.

What this Codex performance workflow gives you

• A read-only diagnosis prompt that returns ranked bottlenecks with file paths and evidence, and changes nothing.
• A benchmark harness and a committed baseline that Codex is not allowed to edit, so a claimed speed-up is a measured one.
• A best-of-N cloud task that tries up to four optimization strategies, and the commands to compare and apply one attempt.
• A verification sequence that proves the change without reading every line of the diff.
• A weekly regression check where a script decides pass or fail and Codex only explains a failure.

The stage before this one is operating Codex day to day. Prerequisite: a Codex cloud environment whose setup script can seed the database; see Codex cloud environments. For the same loop with other agents, see performance analysis with Claude Code and performance optimization with Cursor.

Why does Codex performance work start with a benchmark, not a fix?

An agent asked to “make it faster” reports a number, and that number comes from a run you did not see, on data you did not choose. Performance changes also fail quietly: a cache that serves stale data or an index that locks a table in production both pass the unit tests. So the order is fixed:

1. Diagnose with a read-only sandbox, so nothing changes while you look.
2. Commit a benchmark and a baseline before any optimization exists.
3. Let Codex try strategies against that benchmark in isolated cloud containers.
4. Re-run the benchmark yourself, outside the agent, and merge only on that result.

Each step below produces an artifact the next step checks: a report, a harness, a set of diffs, and a pass or fail.

Diagnose the bottleneck without changing code

Start the diagnosis in the read-only sandbox, so Codex can read code and run read-only commands but cannot edit files. Diagnosis rewards deeper reasoning, and GPT-6 Astra (the Codex default) runs at low effort unless you raise it. Run in your terminal, at the repository root:

codex --sandbox read-only -c model_reasoning_effort="high"

If a read-only database MCP server is already configured for Codex (codex mcp list shows it), Codex can run EXPLAIN on the real query plans instead of guessing them. Which servers to use, and how to keep them read-only, is covered in production performance optimization.

Copy-paste prompt: diagnose a slow endpoint, read-only

GET /api/dashboard has a p95 latency of 2.1 s in production; the target is under 500 ms.
Do not edit any files. Diagnosis only.

1. Start at the route handler and trace every call in the request path, including
   middleware, service calls, database queries, and cache reads.
2. For every database query, record the file and line, the tables it touches, and whether
   it runs once per request or once per row (N+1). If a database MCP server is available,
   run EXPLAIN on each query and quote the plan; otherwise say that the plan is unverified.
3. Flag sequential awaits on independent calls, full objects loaded where only IDs are used,
   and cache reads whose key includes a per-request value such as a timestamp.
4. Rank the top three bottlenecks by expected impact. For each one give the evidence
   (plan, loop, or code path), the file paths, and a way to measure it in isolation.

Separate what you verified from what you inferred.

The last line matters more than it looks. A diagnosis that mixes measured plans with guesses sends you to optimize the guess. Treat any bottleneck marked “inferred” as a hypothesis for the benchmark to confirm.

Build a benchmark harness Codex cannot game

The harness is the oracle for everything that follows, so it lands in its own commit before any optimization. Two rules make it trustworthy:

• Production-scale data. Seed at least 100,000 rows for the tables the diagnosis named, with a realistic distribution (a few heavy users, many light ones). N+1 patterns and missing indexes are invisible on a thousand rows.
• Repeatable numbers. Warm-up requests, several runs, and the median of each run’s p95. A single run on a busy machine measures the machine.

Copy-paste prompt: write the benchmark harness and baseline

Create a benchmark harness for GET /api/dashboard. Do not change application code.

1. scripts/seed-perf.ts: seed 100,000 users and 12 months of orders, with 5% of users
   owning 60% of the orders. Make it idempotent and deterministic (fixed random seed).
2. perf/bench.mjs: start from an already running server at BASE_URL, send 200 warm-up
   requests, then run autocannon with 50 connections for 20 seconds, five times.
   Print JSON: {"endpoint", "runs": [p50, p95, p99 per run], "median_p95"}.
   Exit with code 1 if median_p95 is more than 10% above perf/baseline.json.
   If perf/baseline.json is missing, print the JSON and exit 0 without comparing.
3. Run the seed and the benchmark, then write the result to perf/baseline.json.
4. Add a "perf" section to AGENTS.md: "Files in perf/ and scripts/seed-perf.ts are the
   benchmark oracle. Never edit them in an optimization task."

Report the exact commands you ran and the median p95.

Review this diff yourself; it is the one diff in the loop worth reading line by line, because every later decision trusts it. Then commit it. From here on, any optimization diff that touches perf/ or scripts/seed-perf.ts is rejected without discussion.

Run competing optimizations as best-of-N cloud tasks

codex cloud exec --attempts N runs N independent agents on the same prompt, each producing its own diff. The CLI accepts 1 to 4 and rejects any other value (checked on 0.157.1), and codex cloud as a whole is marked experimental. Each attempt is a separate agent run that draws on your plan’s 5-hour and weekly allowance, so N attempts use about N times the allowance of one; see Codex cost management.

Best-of-N pays off in performance work because the strategies trade off differently: a rewritten query changes one file, a cache adds infrastructure and an invalidation problem, and parallel fetches change error handling. Attempts given the same prompt tend to converge, so name the alternatives and make each attempt state which one it took.

Before you submit, the cloud environment must be able to run the harness: its setup script installs dependencies, starts the database, and runs scripts/seed-perf.ts. Codex cloud environments covers setup scripts, caching, and agent internet access. Push the harness commit first, because the container clones your branch from the remote.

Copy-paste prompt: best-of-N optimization task

Reduce the median p95 of GET /api/dashboard below 500 ms, measured by perf/bench.mjs.

The diagnosis found: (1) an N+1 query in src/services/dashboard.ts when summarizing
orders, (2) no index on orders(user_id, created_at), (3) three independent fetches
awaited one after another.

Pick exactly ONE primary strategy and state it in the first line of your summary:
A) rewrite the queries into one aggregation plus the composite index;
B) parallelize the independent fetches and remove the N+1 with a batched loader;
C) cache the summary per user with a TTL of 5 minutes, with invalidation on order writes.

Rules:
- Do not edit anything in perf/, scripts/seed-perf.ts, or existing test assertions.
- Put any index in a new migration file. On PostgreSQL, use CREATE INDEX CONCURRENTLY.
- If you add a cache, add a test that writes an order and proves the next read is fresh.
- Run scripts/seed-perf.ts, then perf/bench.mjs on the unchanged code and again after
  your change, in this same container. Quote both JSON outputs.
- Run the full test suite and quote the command and its result.

Submit it from your terminal, inside the repository, with the prompt saved to a file:

git push origin perf/dashboard
codex cloud exec --env perf-test --branch perf/dashboard --attempts 3 - < prompts/dashboard-perf.md

perf-test is the label or ID of your cloud environment, and - reads the prompt from standard input. The command prints a task URL; its ID is the TASK_ID for the commands below.

Choose an attempt by evidence, not by the best number

Compare attempts on metadata and numbers before you open any diff:

# Status, attempt count, and size of each task in this environment
codex cloud list --env perf-test --json \
  | jq '.tasks[] | {id, status, attempt_total, summary}'

# Save every attempt's diff for comparison
for n in 1 2 3; do codex cloud diff TASK_ID --attempt "$n" > "attempt-$n.diff"; done

The container is not your production hardware, so compare each attempt’s before and after inside the same container, not absolute milliseconds across attempts. Then weigh the gain against what the attempt adds:

Question	Prefer the attempt that…	Reject when…
Did it hit the target?	Clears 500 ms with the before and after from the same container	Quotes no before number, or only one run
How large is the change?	Touches the fewest files for the gain	Touches perf/, test assertions, or snapshots
What does it add to operate?	Adds no new service	Adds a cache with no freshness test
Is the migration safe?	Uses a non-blocking index build	Builds an index that locks a hot table

Copy-paste prompt: compare the attempts

Do not edit any files. Read attempt-1.diff, attempt-2.diff and attempt-3.diff and the
task summaries I paste below.

For each attempt report: the strategy it claims (A, B or C), the before and after
median_p95 it quoted, the files it changed, and whether it touched perf/,
scripts/seed-perf.ts, test assertions, snapshots, or lockfiles.
Flag any cache without an invalidation test and any index built without CONCURRENTLY.
Recommend one attempt with the reason, or say none is acceptable and what the
follow-up prompt must add. Do not combine attempts unless I ask.

If two attempts each win on a different bottleneck, apply one, re-baseline, and run a second task for the next bottleneck. A hand-merged combination of two attempts is a new, unmeasured change.

Verify the optimization without reading every line

The agent’s quoted numbers tell you which attempt to try, not whether to merge it. Verification happens outside the agent, and a named person signs off.

1. Apply the attempt in a clean worktree. Run in your terminal, from the main checkout:

   git fetch origin perf/dashboard
   git worktree add --detach ../verify-perf origin/perf/dashboard && cd ../verify-perf
   codex cloud apply TASK_ID --attempt 2
   git diff --stat -- perf/ scripts/seed-perf.ts   # must print nothing

2. Re-run the gates yourself. Run the type check, the linter, and the full test suite, then seed and benchmark: node perf/bench.mjs exits non-zero if the median p95 is more than 10% above the baseline. The number that counts is this one, not the one in the task summary.

3. Check the query plan, not the code. If the change adds an index, run EXPLAIN on the new query against the seeded database and confirm that the plan uses it. A composite index in the wrong column order compiles, passes tests, and does nothing.

4. Open the pull request with the evidence. Paste the before and after JSON and the plan into the description, and ask for @codex review on the pull request. Route any migration or cache change to the service’s code owner; see code review with Codex.

5. Prove it in production and keep a way back. Ship behind a feature flag or to a canary, compare p95 in your application’s traces for the same endpoint over the same window, and roll back when it does not improve. The developer who submitted the task owns the merge and the rollback call.

When the change passes, update perf/baseline.json in its own commit, so the next regression check measures against the new number.

Catch performance regressions every week

A weekly check keeps the gain. Let a script make the pass or fail decision and use Codex only to explain a failure, because an agent asked “did performance regress?” can talk itself into either answer.

Schedule node perf/bench.mjs in CI (for example, a weekly schedule trigger). When it exits non-zero, run a headless, read-only Codex step that writes its triage to a file:

status=0
node perf/bench.mjs > perf/latest.json || status=$?   # survives bash -e on CI runners
if [ "$status" -ne 0 ]; then
  codex exec --sandbox read-only --ephemeral -o perf/triage.md - < prompts/perf-triage.md
fi
exit "$status"

Check out full history (for example, fetch-depth: 0 in actions/checkout), otherwise the triage step’s git log sees only one commit. The script keeps the benchmark’s exit code, so the job stays red on a regression and scheduled-failure notifications still fire; the triage file is an attachment to that failure, not a verdict. -o (--output-last-message) writes the final message to a file your job can attach to an issue, and --ephemeral keeps the session off disk. Give the job a timeout, because codex exec has no spend cap (checked on 0.157.1). Authentication, secrets, and the workflow file are covered in CI/CD with Codex and running Codex non-interactively. To run the same check from the desktop app instead, see Codex automations.

Copy-paste prompt: explain a benchmark regression

Do not edit any files. perf/latest.json shows a median p95 above the limit in
perf/baseline.json.

1. Quote both numbers and the endpoint.
2. List the commits since the date of perf/baseline.json that touched files in the
   request path of that endpoint (git log with paths), newest first.
3. For the three most likely commits, explain the mechanism: new query, removed index,
   added await, larger payload, or cache key change. Cite file and line.
4. Propose one experiment per suspect that would confirm or clear it, such as
   benchmarking with that commit reverted.

Mark every claim as verified (you ran or read it) or inferred.

A human reads the triage and decides the next step: revert, open an optimization task, or accept a deliberate trade-off and re-baseline.

When Codex performance work goes wrong

Symptom	Cause	Recovery
The fix is fast locally and slow in production	Benchmark data far smaller than production	Seed at production scale in the cloud environment’s setup script; re-baseline before the next attempt
The benchmark improves but users see no change	The attempt edited the harness, the seed, or a test	Reject any diff touching perf/; keep the “benchmark oracle” rule in AGENTS.md and check git diff --stat in step 1 of verification
All attempts return the same approach	Same prompt, no named alternatives	Name the strategies and require each attempt to state its choice
Numbers swing between runs	Noisy machine, no warm-up, one run	Five runs, warm-up requests, median p95; compare before and after in one container
Users see stale data after a cache change	TTL without invalidation on writes	Require a freshness test in the prompt; roll back the flag, then add invalidation
The deploy locks a table	Index built with a blocking statement on a hot table	Use a non-blocking build (CREATE INDEX CONCURRENTLY on PostgreSQL) in its own migration; see database work with Codex
The triage names no suspect commits	Shallow CI checkout, so git log sees one commit	Fetch full history (fetch-depth: 0) in the scheduled job
Best-of-N drains the weekly allowance	Four attempts on a mechanical change	Use attempts only where strategies differ; one attempt for a known fix

Where to go next with performance

• Codex cloud environments: setup scripts, network access, and best-of-N in depth.
• Load, stress, and benchmark testing: turn the harness into a load-test and CI gate for every service.
• Production performance optimization: diagnose p99 regressions, pool exhaustion, and autoscaling with read-only MCP servers.
• Database work with Codex: queries, indexes, and migrations the agent writes safely.
• Codex cost management: what best-of-N and scheduled runs cost against your allowance.
• Security audits with Codex: the next page in this stage.