Creates a named list of items for parallel processing. Use this tool when you need to perform the same operation across multiple files, URLs, or any collection of items.

WHEN TO USE:

• Before running shell commands or AI agents across multiple items

• When you have a collection of file paths, URLs, identifiers, or any strings to process in parallel

WORKFLOW:

1. Call create_list with your array of items

2. Use the returned list_id with run_shell_across_list or run_agent_across_list

3. The list persists for the duration of the session

EXAMPLE: To process files ["src/a.ts", "src/b.ts", "src/c.ts"], first create a list, then use run_shell_across_list or run_agent_across_list with the returned id.

Creates a list by running a shell command and parsing its newline-delimited output.

WHEN TO USE:

• When you need to create a list from command output (e.g., find, ls, grep, git ls-files)

• When the list of items to process is determined by a shell command

• As an alternative to manually specifying items in create_list

EXAMPLES:

• "find src -name '*.ts'" to get all TypeScript files

• "git ls-files '*.tsx'" to get all tracked TSX files

• "ls *.json" to get all JSON files in current directory

• "grep -l 'TODO' src/**/*.ts" to get files containing TODO

WORKFLOW:

1. Call create_list_from_shell with your command

2. The command's stdout is split by newlines to create list items

3. Empty lines are filtered out

4. Use the returned list_id with run_shell_across_list or run_agent_across_list

Retrieves the items in an existing list by its ID.

WHEN TO USE:

• To inspect the contents of a list before processing

• To verify which items are in a list

• To check if a list exists

Updates an existing list by replacing its items with a new array.

WHEN TO USE:

• To modify the contents of an existing list

• To add or remove items from a list

• To reorder items in a list

Deletes an existing list by its ID.

WHEN TO USE:

• To clean up lists that are no longer needed

• To free up memory after processing is complete

Lists all existing lists and their item counts.

WHEN TO USE:

• To see all available lists in the current session

• To find a list ID you may have forgotten

• To check how many lists exist

Executes a shell command for each item in a previously created list. Commands run in batches of 10 parallel processes, with stdout and stderr streamed to separate files.

WHEN TO USE:

• Running the same shell command across multiple files (e.g., linting, formatting, compiling)

• Batch processing with command-line tools

• Any operation where you need to execute shell commands on a collection of items

HOW IT WORKS:

1. Each item in the list is substituted into the command where $item appears

2. Commands run in batches of 10 at a time to avoid overwhelming the system

3. Output streams directly to files as the commands execute

4. This tool waits for all commands to complete before returning

AFTER COMPLETION:

• Read the stdout files to check results

• Check stderr files if you encounter errors or unexpected output

• Files are named based on the item (e.g., "myfile.ts.stdout.txt")

VARIABLE SUBSTITUTION:

• Use $item in your command - it will be replaced with each list item (properly shell-escaped)

• Example: "cat $item" becomes "cat 'src/file.ts'" for item "src/file.ts"

Spawns an AI coding agent for each item in a previously created list. Agents run in batches of 10 parallel processes with automatic permission skipping enabled.

WHEN TO USE:

• Performing complex code analysis, refactoring, or generation across multiple files

• Tasks that require AI reasoning rather than simple shell commands

• When you need to delegate work to multiple AI agents working in parallel

AVAILABLE AGENTS:

• claude: Claude Code CLI (uses --dangerously-skip-permissions for autonomous operation)

• gemini: Google Gemini CLI (uses --yolo for auto-accept)

• codex: OpenAI Codex CLI (uses --dangerously-bypass-approvals-and-sandbox for autonomous operation)

• opencode: OpenCode CLI (uses run command for non-interactive autonomous operation)

HOW IT WORKS:

1. Each item in the list is substituted into the prompt where {{item}} appears

2. Agents run in batches of 10 at a time to avoid overwhelming the system

3. Output streams directly to files as the agents work

4. This tool waits for all agents to complete before returning

AFTER COMPLETION:

• Read the stdout files to check the results from each agent

• Check stderr files if you encounter errors

• Files are named based on the item (e.g., "myfile.ts.stdout.txt")

VARIABLE SUBSTITUTION:

• Use {{item}} in your prompt - it will be replaced with each list item

• Example: "Review {{item}} for bugs" becomes "Review src/file.ts for bugs" for item "src/file.ts"