ctx_batch_execute
Run many commands in one call, auto-index every output, and search them in a single round trip.
ctx_batch_execute runs a set of related commands together — it works best with
several at once (typically three or more), though one or two are accepted too.
Every output is auto-indexed into the knowledge base, and the queries you supply
are answered from that output in the same response — no separate search call. One
round trip replaces a sequence of run-then-read-then-search steps.
The effect on context is large. A batch whose raw output totals 986 KB returns roughly 62 KB of relevant sections — a 93.7% reduction.
Parameters
| Parameter | Required | Description |
|---|---|---|
commands | yes | Array of objects, each with a label and a command. At least one. |
queries | yes | Array of questions to answer from the batch output. At least one is required — aim for 5 to 8 comprehensive queries, since this is your one chance to ask. |
concurrency | no | 1 to 8. Default 1. |
timeout | no | Max execution time in milliseconds. When omitted, the MCP host's RPC timeout governs. With concurrency: 1 a set value is a shared budget across commands; with concurrency above 1 it applies per command. |
cwd | no | Working directory for all commands in the batch. |
query_scope | no | batch (this batch only, the default) or global (the whole persistent index, same scope as ctx_search). |
Each label becomes the title of the FTS5 chunk that holds that command's
output, so use descriptive labels — they are how the relevant section is found and
returned.
Concurrency
Set concurrency to match the work. Use 4 to 8 for I/O-bound commands that spend
their time waiting, such as network requests, gh calls, or cloud API queries.
Keep it at 1 for CPU-bound work like builds and tests, and for stateful commands
that share a resource, such as port binders or anything writing to the same files.
A value above 1 also changes timeout handling: each command gets its own timeout
and a command that exceeds it returns an individual (timed out) block, rather
than the shared budget and cascading skip used at concurrency: 1.
Think in Code still applies inside a batch. Add a final command that consumes the earlier output and prints only the answer, so the conclusion returns directly instead of the raw bytes.
Example
This batch runs two gh commands and answers two questions from their combined
output in one call.
ctx_batch_execute(
commands: [
{ label: "open PRs", command: "gh pr list --state open --json number,title,author" },
{ label: "recent issues", command: "gh issue list --state all --limit 50 --json number,title,state" }
],
queries: [
"Which PRs are still open and who authored them?",
"How many issues were closed recently?"
],
concurrency: 4
)Both command outputs are indexed under their labels, and the sections that answer
each query return together. Set query_scope to global if you want the queries
to search the entire knowledge base rather than only this batch.
When to use it
Reach for ctx_batch_execute when you have several related commands and
questions to answer from their combined output. For a single command, prefer
ctx_execute instead — a batch still runs with one
command, but its strength is grouping several into one round trip.