Codex Runs Tool Calls One by One? Batch Them Safely

If Codex is reading files, searching code, or inspecting APIs one call at a time even when the calls are independent, make the dependency boundary explicit. Ask it to group independent read-only operations into one native parallel batch, wait for every result, and keep dependent work, approvals, and writes sequential.

Use this instruction:

Before calling tools, map the dependencies. Group independent read-only
operations into one parallel batch using the runtime's supported native
parallel mechanism. Keep a call sequential when its input depends on an
earlier result. Keep approvals, waits, and writes sequential. Inspect every
result before continuing, and do not replace native tool calls with shell
background jobs or an ad hoc script

That is a scheduling instruction, not a promise of lower usage. A July 2026 community report measured 27% to 45% lower weighted usage in two controlled tasks after adding a batching instruction, but one prompt variant used 26.8% more. Treat those numbers as a reason to test your own workflow, not as an OpenAI benchmark or guaranteed quota workaround.

When Parallel Tool Calls Are Actually Safe

Two operations are independent when neither needs the other's result and neither changes state that the other reads.

Good batch candidates include:

• reading three known files;

• searching three unrelated terms;

• listing issues, pull requests, and releases for the same repository;

• inspecting several read-only integration schemas;

• fetching independent documentation pages.

Keep these sequential:

• discover a file path, then open that path;

• inspect a schema, then construct an input that must conform to it;

• request approval, then perform the approved action;

• update a record, then verify the updated state;

• start a long-running job, then poll its result;

• any write whose ordering or rollback behavior matters.

The test is simple: if call B needs any value or side effect from call A, B must wait.

Prerequisites

Use a fresh, bounded task that has several independent reads and a result you can verify. Record:

• the Codex surface and version;

• the selected model and reasoning effort;

• the repository commit and working-tree state;

• the prompt and permission mode;

• the expected files, records, or facts in the answer.

Do not benchmark on an active migration, release, deletion, or production write. A read-only task makes incorrect scheduling easier to detect and keeps the comparison reversible.

Step 1: Run a Baseline Without the Instruction

Choose a task with four independent reads. For example:

Read package.json, pnpm-workspace.yaml, AGENTS.md, and README.md.
Return the package manager, workspace layout, local assistant rules, and
primary setup command. Do not edit files

Start a fresh Codex session and run the prompt once. Record:

• how many tool-call cycles occurred;

• whether independent reads appeared in the same batch;

• elapsed time, if the UI exposes it;

• usage, if the product exposes a comparable usage measure;

• whether all four requested facts were correct.

Do not infer token savings from elapsed time alone. Network latency, cache state, model load, and response length can all change the duration.

Step 2: Add the Safe Batching Instruction

Start another fresh session with the same model, reasoning effort, permissions, repository commit, and task. Add the instruction from the opening of this guide before the task.

Expected result: Codex identifies the four reads as independent, submits them together through its supported tool path, receives every result, and then produces one answer. It should not invent a shell loop, background processes, or a temporary script just to imitate parallelism.

OpenAI's Codex prompting guidance recommends batching independent reads, list operations, and searches while keeping dependent operations sequential. It also recommends using the runtime's native parallel path instead of routing native tool work through a script.

Step 3: Verify Coverage, Not Just Speed

Compare the second run with the baseline. The batched run is only an improvement if it preserves the result contract.

Check that:

1. every requested source was read;

2. no result was silently dropped after one call failed;

3. the answer distinguishes missing evidence from a negative finding;

4. no file or external record changed;

5. the task used fewer call cycles or improved another measured outcome without reducing accuracy.

If the batch returns a partial failure, retry only the failed read when it is safe and independent. Do not rerun successful calls reflexively, especially when an API has cost or rate limits.

Step 4: Make the Rule Durable in AGENTS.md

If the controlled run helps, add a short project-scoped rule to the repository's AGENTS.md:

- Before tool calls, identify dependencies. Batch independent read-only
  operations through the runtime's native parallel mechanism. Keep dependent
  calls, approvals, waits, and writes sequential, and inspect every result

Keep the rule semantic. Internal tool names and implementation details can change, while the dependency boundary stays useful. Do not require a specific Promise.all(...) wrapper, shell operator, or private tool identifier in long-lived project instructions.

If Codex already batches the task correctly, skip the extra rule. More prompt text is not automatically better.

Step 5: Test a Real Multi-Source Search

Aident Loadout exposes a useful bounded test because one search can return independent capability results without asking you to paste provider keys.

First, install or refresh the Aident skill in Codex:

Follow https://aident.ai/SETUP.md

Confirm authentication and connected services:

aident account auth status
aident vault vault --action status

Then run one batch search from a trusted shell:

aident capabilities search \
  --queries '["search GitHub issues","inspect web analytics","search recent videos"]' \
  --types '["action"]'

Expected result: the JSON response reports success: true and includes one resultsByQuery entry for each of the three queries. Search is read-only; do not execute any returned Action until you inspect its current schema and confirm its risk.

Now ask Codex:

Inspect the current input schemas for the first read-only Action returned by
each query. These schema reads are independent, so batch them through the
supported native parallel mechanism. Return the exact Action names and their
required input fields. Do not execute the Actions

Measure success as three schemas inspected, zero integration writes, zero provider secrets pasted, and no missing result hidden by the batch.

Common Failure Modes

Why the Instruction Can Help

An agent may know that parallel calls exist without consistently deciding which operations are independent. A short scheduling rule moves that decision before execution: build the dependency graph, batch the ready read-only nodes, inspect the results, then advance to the next dependent layer.

The benefit is fewer tool-call round trips. It does not make the underlying tools faster, reduce the size of every result, or guarantee lower model usage. Large responses can still dominate context, and unsafe batching can create rework.

The strongest public evidence is still user-reported. OpenAI Codex issue #35050 described four batched runs and three controls on a large-repository task plus four paired finance runs. The reporter measured fewer call cycles and lower weighted usage with an explicit instruction, but also documented a worse prompt variant. An earlier trace in issue #32503 reported only 5 parallel batches across 739 Code Mode execution cells. These observations identify a reproducible question, not a universal defect rate.

That is why the useful fix is modest: batch only operations you can prove are independent, keep state changes ordered, and retain the instruction only when a controlled comparison preserves coverage and improves a metric you care about.

For related Codex usage symptoms, see How to Diagnose Codex Usage Spikes. For durable project instructions, see How to Make Codex Review Code the Way Your Team Does.

Sources

• Codex prompting guide: parallel tool calling, OpenAI, accessed July 28, 2026

• GPT-5.6 often serializes independent Code Mode calls, OpenAI Codex issue, opened July 24, 2026

• GPT-5.6 fails to parallelize independent tool calls, OpenAI Codex issue, opened July 12, 2026

• Possible GPT-5.6 usage workaround: explicit tool call batching, r/codex, posted July 24, 2026

• Explicit Codex batching instruction shared on X, X, posted July 27, 2026

• Codex dependency-graph batching example on X, X, posted July 25, 2026

• Aident setup instructions, accessed July 28, 2026