Batch Execute & Search
ctx_batch_executeRun multiple related commands in one call, auto-index their output, and pass queries to get matching sections back in the same round trip—avoiding sequential command runs.
Instructions
Run multiple commands in ONE call. Every command's output is auto-indexed into the knowledge base; pass queries and the matching sections come back in the same round trip. Concurrency parallelizes the fetch phase only — derivation still belongs in code, so add a processing command that consumes indexed output and prints just the answer.
WHEN:
You have 3+ related commands you would otherwise run sequentially (multi-issue lookups, git log + diff + blame, multi-file reads, multi-region cloud queries)
You want to gather AND query in one round trip — pass
queriesso 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)Combined output is large enough that a later ctx_search pass would itself be expensive
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 racing on the same resource)
RETURNS: Auto-indexed section list per command label, plus top matches per query. Raw output is NOT echoed in full.
EXAMPLE: ctx_batch_execute( commands: [ {label: "issue 1", command: "gh issue view 1"}, {label: "issue 2", command: "gh issue view 2"} ], 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 |