sweeper

🧹 Sweeper Agent

Multi-threaded code maintenance with resource isolated subagents and swappable AI providers.

Sweeper dispatches parallel AI agents to fix lint issues across your codebase, each running in its own isolated environment. Providers are swappable: use Claude Code (default), OpenAI Codex, or local models via Ollama. It groups issues by file, fans out concurrent fixes, escalates strategy when fixes stall, and records outcomes so it learns what works. With VM isolation enabled, each sub-agent runs inside a dedicated stereOS virtual machine with its own CPU, memory, and secrets boundary, safe to scale to 10+ concurrent agents.

                        sweeper run --vm -c 5
                              │
                    ┌─────────┼─────────┐
                    ▼         ▼         ▼
              ┌──────────────────────────────┐
              │        Worker Pool           │
              │ (rate-limited, max N=5)      │
              └──┬───┬───┬───┬───┬──────────┘
                 │   │   │   │   │
                 ▼   ▼   ▼   ▼   ▼
               ┌───┐┌───┐┌───┐┌───┐┌───┐
               │VM ││VM ││VM ││VM ││VM │  ◄── stereOS isolation
               │ 1 ││ 2 ││ 3 ││ 4 ││ 5 │      (secrets, CPU, memory)
               └─┬─┘└─┬─┘└─┬─┘└─┬─┘└─┬─┘
                 │     │     │     │     │
                 ▼     ▼     ▼     ▼     ▼
              claude  claude claude claude claude
              --print --print --print --print --print
                 │     │     │     │     │
                 └─────┴──┬──┴─────┴─────┘
                          │
                    ┌─────┼───────────┐
                    ▼     ▼           ▼
               streaming telemetry  tapes
               progress  (.jsonl)  (SQLite)

Each sub-agent works on a single file. Results stream back as they complete, giving real-time progress instead of blocking until the entire round finishes.

Why Sub-Agents

The main thread never reads or edits source files. It runs the linter, builds prompts, dispatches work, and collects results. All file-level reasoning happens inside sub-agents via claude --print, which are stateless, single-shot processes.

This matters because the orchestrator's context window stays small and predictable. It holds lint output, task metadata, and result summaries, not the contents of every file being fixed. A run that touches 50 files uses roughly the same orchestrator context as one that touches 5. The complexity scales in parallelism, not in context size.

  Orchestrator (main thread)              Sub-agents (disposable)
  ┌────────────────────────┐
  │ lint output            │              ┌──────────────────────┐
  │ file groupings         │  ──dispatch──▶ claude --print       │
  │ strategy decisions     │              │  reads auth.go       │
  │ result summaries       │  ◀──result── │  writes fix          │
  │                        │              └──────────────────────┘
  │ (never sees file       │              ┌──────────────────────┐
  │  contents directly)    │  ──dispatch──▶ claude --print       │
  │                        │              │  reads router.go     │
  │                        │  ◀──result── │  writes fix          │
  └────────────────────────┘              └──────────────────────┘

Sub-agents are fire-and-forget. Each one gets a prompt with the lint issues for its file, does the work, and exits. If it fails, the orchestrator knows from the exit code and can retry with an escalated strategy on the next round. No conversation state carries over between rounds, which keeps each attempt clean.

Setup

Go CLI (standalone)

The core binary. All integrations below (except Pi) require this.

go install github.com/papercomputeco/sweeper@latest
sweeper run                              # default: golangci-lint with claude
sweeper run --provider codex             # use OpenAI Codex CLI instead
sweeper run --provider ollama --model qwen2.5-coder:7b  # local model via Ollama
sweeper run --vm -c 3 --max-rounds 3    # VM isolation, 3 agents, 3 rounds
sweeper run -- npm run lint              # any linter
sweeper observe                          # review success rates + token spend

Claude Code

To use sweeper as a skill in Claude Code:

1. Build the binary:

go build -o sweeper .
export PATH="$PWD:$PATH"

2. Copy the skill into your project:

cp -r skills/sweeper/ /path/to/your-project/.claude/skills/sweeper/

3. Tell Claude: "Run sweeper on this project"

Claude will orchestrate sweeper run with the right flags based on your project.

Plugin support: This repo includes a .claude-plugin/ manifest for distribution as a Claude Code plugin, but it is not yet published to the plugin marketplace. If there is community interest, I am happy to submit it.

opencode