Batch Execute & Search
ctx_batch_executeRun multiple shell commands in parallel, auto-index each output, and return query matches in one round trip so no follow-up search is needed.
Instructions
Run multiple commands in ONE call. Every command's output is auto-indexed into the knowledge base; if you also pass queries, the matching sections come back in the same round trip so a follow-up search call is not needed.
Concurrency parallelizes the FETCH phase (run-the-commands). The DERIVATION phase — turning raw output into an answer — still belongs in code: add a processing command that consumes the indexed output and prints only the answer, so the raw bytes never enter your conversation (Think-in-Code, same principle as the sandbox tool).
WHEN:
You have 3+ related commands you would otherwise run sequentially (multi-issue lookups, git log + git diff + git blame, multi-file reads, multi-region cloud queries)
You want to gather AND query in one round trip — pass
queriesso the matching sections come back inlineYou want to parallelize I/O-bound work — pass
concurrency2-8 (network calls, gh CLI, cloud APIs, multi-repo git reads)The combined output is large enough that piping it through ctx_search later would itself be expensive — let auto-index + inline queries do both in one shot
WHEN NOT:
Single command with no follow-up query — run it in the sandbox tool directly
CPU-bound or stateful commands — keep concurrency at 1 (npm test, build, lint, port-binding servers, lock-file holders, anything that races on the same resource)
RETURNS:
Auto-indexed section list per command label, plus top matches per query (when queries is passed). Raw output is NOT echoed in full — only the matched windows. Concurrency>1 switches each command to its own per-command timeout (no shared budget); concurrency=1 preserves the legacy shared-budget cascading-skip-on-timeout path. Use 4-8 for I/O-bound batches; keep at 1 for CPU work or shared-state commands; lower the value when target hosts enforce per-IP rate limits.
EXAMPLE: ctx_batch_execute( commands: [ {label: "issue 1", command: "gh issue view 1"}, {label: "issue 2", command: "gh issue view 2"}, {label: "summarize", command: "echo done"} ], queries: ["root cause", "proposed fix"], concurrency: 2 )
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Optional working directory for all shell commands in this batch. | |
| queries | Yes | Search queries to extract information from indexed output. Use 5-8 comprehensive queries. Each returns top 5 matching sections with full content. This is your ONLY chance — put ALL your questions here. No follow-up calls needed. | |
| commands | Yes | Commands to execute as a batch. Output is labeled with the section header. Default order is sequential; pass concurrency>1 to run in parallel (output stays in input order). | |
| timeoutMs | No | Max execution time in MILLISECONDS — timeoutMs: 120000 is two minutes, timeoutMs: 120 is 0.12 seconds. When omitted, the host's own RPC timeout governs where it has one; on hosts that do not bound a call (Pi, Antigravity CLI) a generous server-side default applies per command. With concurrency=1, a value you pass is a shared budget across commands; with concurrency>1, it is applied per-command. | |
| concurrency | No | Max commands to run in parallel (1-8, default: 1). Use 4-8 for I/O-bound batches (network, gh, curl, multi-repo git reads). Keep at 1 for CPU-bound (npm test, build, lint) or stateful commands (ports, locks). >1 switches to per-command timeouts (no shared budget) and individual `(timed out)` blocks instead of cascading skip. | |
| query_scope | No | Scope for `queries` (default: `batch`). `batch` searches ONLY the chunks produced by this batch's commands — useful when you want answers about the just-fetched output. `global` searches the entire persistent index (same scope as ctx_search) — useful when you want the batch commands to enrich context and the queries to also surface related prior knowledge in one round trip. | batch |