| name | batch |
| description | Run a prompt or instruction across multiple files matching a glob pattern |
| tags | ["automation","bulk"] |
| tools_required | ["spawn_agents","list_directory","read_file"] |
| parameters | [{"name":"glob","type":"file_glob","description":"File pattern to process (e.g., \"src/**/*.py\")","required":true},{"name":"instruction","type":"string","description":"What to do with each file","required":true},{"name":"concurrency","type":"integer","description":"Max concurrent sub-agents","default":3}] |
| output_format | json |
| composable | false |
Batch Processing
Run an instruction against every file matching a glob pattern, using sub-agents for parallel execution.
Steps
-
Expand the glob: Use list_directory to walk the directory tree implied by {glob}. Collect the full list of matching file paths. If zero files match, return immediately with {"files_processed": 0, "error": "no files matched pattern"}.
-
Preview: Log the total count of matched files. If more than 50 files match, warn the user and ask for confirmation before proceeding (unless running autonomously).
-
Read and validate: For each file, use read_file to confirm it exists and is readable. Skip binary or unreadable files and note them in a skipped list.
-
Spawn sub-agents: Use spawn_agents to fan out processing. Pass each sub-agent:
- The file path and its contents
- The instruction:
{instruction}
- A unique task ID derived from the file path
Limit concurrency to
{concurrency} simultaneous agents.
-
Collect results: As each sub-agent completes, capture its output. Track successes, failures, and any errors with the originating file path.
-
Summarize: Return a JSON object:
{
"files_processed": <int>,
"succeeded": [{"file": "...", "result": "..."}],
"failed": [{"file": "...", "error": "..."}],
"skipped": ["..."]
}
Error Handling
- If a sub-agent fails, record the error and continue with remaining files.
- If more than half the files fail, include a
warning field in the output suggesting the instruction may need adjustment.
- Never abort the entire batch on a single-file failure.