Ruflo: turn Claude into a parallel agent swarm on your laptop, free

Here is the quick start I ran on a fresh machine. Ruflo expects Python 3.11+, Git, and an Anthropic key. The manager coordinates workers that research, draft, and implement in parallel. You give Ruflo a task, it breaks that into subgoals, then streams progress so you can watch jobs finish in parallel.

Install Ruflo system wide with pipx. Pipx keeps CLI tools isolated, which avoids version fights with your projects.

bash
pipx install ruflo

Export your Anthropic key so workers can call Claude. Use a real key that starts with sk-ant.

bash
export ANTHROPIC_API_KEY="sk-ant-1234567890abcdef0123456789abcdef"

Verify the CLI is on your path and the key is visible.

bash
ruflo --version && ruflo env

You should see a version like ruflo 0.x.y and ANTHROPIC_API_KEY set. Stop here if that is not true. Next step is running a sample task, but save that for the full guide so we keep config simple.

Here is the quick start I ran on a fresh machine. Ruflo expects Python 3.11+, Git, and an Anthropic key. The manager coordinates workers that research, draft, and implement in parallel. You give Ruflo a task, it breaks that into subgoals, then streams progress so you can watch jobs finish in parallel.

Install Ruflo system wide with pipx. Pipx keeps CLI tools isolated, which avoids version fights with your projects.

bash
pipx install ruflo

Export your Anthropic key so workers can call Claude. Use a real key that starts with sk-ant.

bash
export ANTHROPIC_API_KEY="sk-ant-1234567890abcdef0123456789abcdef"

Verify the CLI is on your path and the key is visible.

bash
ruflo --version && ruflo env

You should see a version like ruflo 0.x.y and ANTHROPIC_API_KEY set. Stop here if that is not true. Next we finish setup per platform, then run the first parallel job.

Setup

macOS

• Install Homebrew if you do not have it:

bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

• Install Python 3.11 and Git:

bash
brew install [email protected] git pipx
pipx ensurepath

• Install Ruflo and set your key:

bash
pipx install ruflo
export ANTHROPIC_API_KEY="sk-ant-1234567890abcdef0123456789abcdef"

Linux (Ubuntu/Debian)

• System deps:

bash
sudo apt update && sudo apt install -y python3.11 python3.11-venv python3-pip git
python3 -m pip install --user pipx
python3 -m pipx ensurepath
exec $SHELL

• Install Ruflo and set your key:

bash
pipx install ruflo
export ANTHROPIC_API_KEY="sk-ant-1234567890abcdef0123456789abcdef"

Windows 10/11

• Install Python and Git:

bash
winget install -e --id Python.Python.3.11
winget install -e --id Git.Git

• Install pipx, then Ruflo:

bash
python -m pip install --user pipx
python -m pipx ensurepath
pipx install ruflo

• Set your key in the current PowerShell:

bash
setx ANTHROPIC_API_KEY "sk-ant-1234567890abcdef0123456789abcdef"
$env:ANTHROPIC_API_KEY = "sk-ant-1234567890abcdef0123456789abcdef"

Verify

Check Ruflo version and that it can reach Anthropic.

bash
ruflo --version
ruflo doctor

Expected output snippets:

• Version line:

text
ruflo 0.8.3

• Doctor check:

text
[ok] Python >= 3.11
[ok] Anthropic key loaded
[ok] Network reachable
[ok] Models: claude-3-5-sonnet-20240620

If doctor shows a red line for the key or network, fix that before running jobs.

First run

Start a minimal swarm to see parallel work. This runs one manager and three workers.

bash
ruflo run \
  --model claude-3-5-sonnet-20240620 \
  --workers 3 \
  --task "Research the top 5 WebAuthn libraries in Python, compare features, and generate a starter FastAPI example with WebAuthn login"

What you will see:

• Manager creates subgoals: scan docs, make comparison table, draft FastAPI example.
• Worker 1 fetches and summarizes docs.
• Worker 2 builds the comparison.
• Worker 3 writes code and tests.
• Artifacts saved under .ruflo/runs/<timestamp> including notes.md and app/

Stop the run with Ctrl+C. The partial artifacts remain in the run folder.

Configuration tips

• Set defaults in a project file so you do not repeat flags:

bash
ruflo init

This creates ruflo.yaml in the current folder. Useful fields:

yaml
model: claude-3-5-sonnet-20240620
workers: 4
max_tokens: 4000
timeout_sec: 120
concurrency: 4
memory:
  kind: file
  path: .ruflo/memory
artifacts_dir: .ruflo/runs
rate_limit_per_min: 60

• Switch model for draft heavy work:

bash
ruflo config set model claude-3-haiku-20240307

• Keep a clean paper trail. Enable verbose logs and save transcripts:

bash
ruflo config set log_level debug
ruflo config set save_transcript true

• Pin tasks to templates for repeat jobs:

bash
ruflo template add research-plan .ruflo/templates/research_plan.yaml
ruflo run --template research-plan --arg topic="WebAuthn in Python"

• Control HTTP retries when you see transient 5xx:

bash
ruflo config set http_retries 3
ruflo config set http_backoff_ms 500

Troubleshooting

• 401 Unauthorized from Anthropic

- Cause: bad or missing ANTHROPIC_API_KEY. - Fix:

bash
unset ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY="sk-ant-1234567890abcdef0123456789abcdef"
ruflo doctor

• 429 Rate limited

- Cause: sending too many parallel requests. - Fix: lower concurrency or pick a smaller model for worker roles.

bash
ruflo config set concurrency 2
ruflo config set rate_limit_per_min 30

• SSL or proxy errors on corporate networks

- Cause: outbound HTTPS intercepted. - Fix: set HTTPS proxy env vars the tool respects.

bash
export HTTPS_PROXY="http://proxy.corp.local:3128"
export HTTP_PROXY="http://proxy.corp.local:3128"
ruflo doctor

When it beats a single Claude chat

• Wide research then code. A single chat walks the steps one by one. Ruflo has one worker skimming docs while another drafts the table and another starts the example. On a 10 minute task, you land closer to 3 to 5 minutes.
• Large refactors. One worker maps the repo, another writes a plan, and a third starts changing files. You keep the manager focused on acceptance tests so it rejects half baked edits.
• Repeat checklists. Stamp out a weekly report with the same template. The manager fills gaps and retries failed steps. You get consistent artifacts in .ruflo/runs with a clean diff from last week.

Sources