Dispatches many independent items in parallel: create a table, fan out to subagents, aggregate results. One row = one unit of work.

Swarm Process many independent items in parallel. create builds a table handle; run fans work out across rows and merges results back. One row = one unit of work — swarm handles batching automatically. Flow 1. Create. Build a table from a source — files, a glob pattern, or pre parsed records. One row per item. Returns a handle. 2. Run. Dispatch an instruction template across rows. Results are merged back into the table. Returns { completed, failed, skipped, failures } . 3. Aggregate. Use rows() and plain JS to count, filter, or summarize. Do not spawn additional subagents for aggregation. 4. Retry. Re run with filter: { column: "<col ", exists: false } to reprocess only failed rows. Choosing a source glob / filePaths — one file = one row. Use when each file is an independent unit of work. Each row gets { id, file } ; the subagent reads the file itself via the {file} placeholder. tasks — pass pre built records directly. Use when the data lives inside a file (JSONL, CSV, JSON array). Read and parse the file first inside eval , then pass the records. One record = one row — do not group multiple items into a single row. For small files (under ~500 lines), parse and create in one block: For large files, read in chunks of 500 lines to avoid truncation: When the file is too large to parse and dispatch in one eval call, split across two blocks. Only the block that calls swarm functions needs the import: Passing filePaths: ["/data.jsonl"] would produce a table with one row pointing at the file — not one row per record inside it. When to use subagentType Omit subagentType for classification, extraction, labeling, and any task where a single model call with structured output is sufficient. This is the default and is significantly cheaper and faster — each dispatch is a direct model call, no tools, no iteration. Set subagentType when the task requires tools, file access, or multi step reasoning. Each dispatch runs a full agentic loop with the named subagent. Instruction + context instruction is a per item template with {column} placeholders. Placeholders are resolved by the framework — your column names appear in prompts as references to the values listed alongside, never as raw template syntax. Subagents do the work — do not process items yourself in JS and write the results into rows. context is free form prose prepended to every subagent prompt. Use it for shared background: domain terms, classification rules, examples, etc. Structured output responseSchema is required. Schema properties become top level columns on each row and constrain what subagents can return. Batching By default, swarm auto batches to keep total dispatches under 10. For small tables (≤10 rows) each row gets its own subagent call. For larger tables, rows are grouped automatically. Set batchSize to control grouping: Number — uniform batch size for all rows. batchSize: 1 forces per row dispatch; batchSize: 20 groups in twenties. Function — (row, rowCount) = number . Returns the desired batch size for each row. Rows with the same batch size are grouped together, then chunked. Allows mixed dispatch where some rows go solo and others batch. Batch sizes are clamped to [1, 50] after evaluation. Aggregation After run() , use rows() and plain JS — no additional subagents needed. Chaining passes run updates the table in place — chain calls to accumulate columns. Action only tasks When subagents perform actions (write a file, apply a fix) rather than return data, use a simple schema with a status or marker field. The exists: false filter still works for retries. Filtering Technical notes Only import @/skills/swarm in blocks where you call swarm functions. Data preparation (reading files, parsing, storing in globalThis ) does not need the import. Destructure only what you use: { create } , { run } , { create, run } , etc. Console output is capped at ~5 KB. Never log raw file contents — log only counts and short samples. readFile inside eval returns raw content — no line number prefixes. Request at most 500 lines per call. For files with more than 500 lines, loop with incrementing offset . When building a table from a file, read it inside eval . Data read inside the sandbox stays there; it never enters the agent's context window. Never write to .swarm/ directly. Always use create() . Everything the subagent needs must be in instruction + context . Subagents can't see the agent's context. Row ids must be unique. create() rejects sources that produce duplicate ids. For tasks , that's a caller side responsibility; for glob / filePaths , ids are auto disambiguated by parent directory. Unknown columns fail fast. If instruction references {foo} and no matched row provides foo , run() throws before any subagent is dispatched. API Reference create(source) Create a table. Returns a handle { id, count, columns } . Source Description { glob: "src/ / .ts" } or { glob: ["src/ / .ts", "lib/ / .ts"] } Match files by one or more patterns. Columns: id , file { filePaths: ["a.ts", "b.ts"] } Explicit file list. Columns: id , file { tasks: [{ id: "t1", text: "..." }] } Custom rows. Each must have id run(tableId, options) Dispatch work across rows. Returns { completed, failed, skipped, failures } . Option Default Description instruction (required) Template with {column} placeholders responseSchema (required) JSON Schema ( type: "object" ) — properties become row columns context — Prose prepended to every subagent prompt filter — Only dispatch matching rows subagentType — Name of subagent to dispatch to. When set, runs a full agentic loop. When omitted, runs a direct model call batchSize auto Number or (row, rowCount) = number . Auto caps dispatches at 10; 1 = per row; function = per row sizing concurrency 10 Max concurrent subagent dispatches (clamped to 1–10) rows(tableId, options?) Retrieve rows. Use for inspection and JS based aggregation. Option Description filter Only return matching rows columns Project to specific columns limit Max rows returned