claude-while

A bash wrapper that runs multiple Claude CLI instances in parallel, each looping continuously.

Installation

Make sure the script is executable and in your PATH:

chmod +x claude-while
# Option 1: symlink to a directory in PATH
ln -s "$(pwd)/claude-while" ~/.local/bin/claude-while

# Option 2: add the directory to PATH
export PATH="$PATH:$(pwd)"

Usage

claude-while --instances N [--delay SECONDS] -- <claude args...>

Options

Option	Description
--instances N or -n N	Number of parallel Claude instances to run
--delay SECONDS	Seconds to wait between each worker's iterations (default: 0, or set via WHILECLAUDE_DELAY env var)
--	Separator between claude-while options and claude arguments

Everything after -- is passed directly to the claude CLI. If you forget -p, it will be added automatically.

Examples

Basic usage

Run 3 instances with a simple prompt:

claude-while --instances 3 -- -p "Find and fix TODO comments in the codebase"

Coordinated multi-agent workflow

Run multiple agents working on related tasks, using a shared file to coordinate:

claude-while --instances 3 -- -p "Find something important related to this concern: we havent released in a week and have a lot of changes. I'm not sure how to get this released without having to do a major QA session. any bug fixes or improvements to recently created items would be good. I'm currently blocked by having to run migrations without db access in prod, the migrations are failing so we built a ux around it. lets really make it solid so the release goes well. There are multiple agents doing this. commit and push when done. update WHILE before you start, make sure not to do the same thing, then edit WHILE when you are done." --allowedTools "Read,Edit,Bash"

With restricted tools

Limit what tools Claude can use:

claude-while --instances 2 -- -p "Review code for security issues" --allowedTools "Read,Grep,Glob"

With delay between iterations

Add a 5-second delay between each worker's runs:

claude-while --instances 2 --delay 5 -- -p "Monitor for changes and report"

Coordination Pattern

When running multiple agents on the same codebase, use a shared coordination file (e.g., WHILE) to prevent duplicate work:

1. Each agent reads WHILE at the start to see what others are doing
2. Agent updates WHILE with what it plans to work on
3. Agent does the work
4. Agent updates WHILE when finished

Example WHILE file content:

Agent 1: Working on fixing login validation - IN PROGRESS
Agent 2: Improving error messages in API - DONE
Agent 3: Adding tests for user service - IN PROGRESS

How It Works

1. Spawns N worker processes in parallel
2. Each worker runs claude with the provided arguments
3. When a Claude instance exits, the worker immediately starts a new one
4. Continues until you kill the process (Ctrl+C)

Stopping

Press Ctrl+C to stop all workers. The script handles cleanup automatically.