feat: add swappable AI provider system (claude, codex, ollama)

Introduce a provider registry so sweeper can use different AI backends
instead of being hardcoded to Claude. Well-scoped subagent tasks like
lint fixes can now run on smaller/cheaper models via Ollama or use
alternative CLI harnesses like Codex.

Two provider categories:
- CLI (claude, codex): have built-in file tools, sweeper sends prompts
- API (ollama): text-in/text-out, sweeper includes file content in
  prompts and applies returned unified diffs via patch

New flags: --provider, --model, --api-base
VM isolation validated to only work with CLI providers.

Author: bdougie

README.md

@@ -1,8 +1,8 @@
 # 🧹 Sweeper Agent
 
-Multi-threaded code maintenance with resource isolated subagents.
+Multi-threaded code maintenance with resource isolated subagents and swappable AI providers.
 
-Sweeper dispatches parallel Claude Code agents to fix lint issues across your codebase, each running in its own isolated environment. 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 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
@@ -65,7 +65,9 @@ The core binary. All integrations below (except Pi) require this.
 
 ```bash
 go install github.com/papercomputeco/sweeper@latest
-sweeper run                              # default: golangci-lint
+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
@@ -122,6 +124,28 @@ pi install sweeper
 
 This gives you `init_sweep`, `run_linter`, and `log_result` tools plus a dashboard widget. To start a sweep, tell Pi: "Sweep this project for lint issues"
 
+## Providers
+
+Sweeper supports swappable AI providers. Well-scoped tasks like lint fixes can run on smaller, cheaper models.
+
+| Provider | Kind | Requires | Example |
+|----------|------|----------|---------|
+| `claude` (default) | CLI | `claude` CLI installed | `sweeper run` |
+| `codex` | CLI | `codex` CLI installed | `sweeper run --provider codex` |
+| `ollama` | API | Ollama running locally | `sweeper run --provider ollama --model qwen2.5-coder:7b` |
+
+**CLI providers** (claude, codex) have built-in file tools. Sweeper sends a prompt and the harness reads/writes files directly.
+
+**API providers** (ollama) are text-in, text-out. Sweeper includes file content in the prompt and applies the returned unified diff via `patch`.
+
+### Provider flags
+
+- `--provider <name>` — AI provider to use (default: `claude`)
+- `--model <name>` — Model override for the provider (e.g. `qwen2.5-coder:7b` for ollama)
+- `--api-base <url>` — API base URL for API providers (default: `http://localhost:11434` for ollama)
+
+VM isolation (`--vm`) is only compatible with CLI providers.
+
 ## Examples
 
 Sweeper works with any command that produces output, not just linters.
@@ -141,6 +165,15 @@ sweeper run -- ./scripts/check-slop.sh
 
 # Higher concurrency with VM isolation
 sweeper run --vm -c 5 --max-rounds 3 -- npm run lint
+
+# Use Codex CLI
+sweeper run --provider codex -- npm run lint
+
+# Use a local Ollama model
+sweeper run --provider ollama --model qwen2.5-coder:7b
+
+# Ollama with a custom API base
+sweeper run --provider ollama --model codellama --api-base http://gpu-server:11434
 ```
 
 When using sweeper as a skill, you can pass arbitrary goals to the agent:

cmd/run.go

@@ -12,6 +12,7 @@ import (
 	"github.com/papercomputeco/sweeper/pkg/agent"
 	"github.com/papercomputeco/sweeper/pkg/config"
 	"github.com/papercomputeco/sweeper/pkg/linter"
+	"github.com/papercomputeco/sweeper/pkg/provider"
 	"github.com/papercomputeco/sweeper/pkg/vm"
 	"github.com/papercomputeco/sweeper/pkg/worker"
 	"github.com/spf13/cobra"
@@ -21,9 +22,13 @@ func newRunCmd() *cobra.Command {
 	var dryRun bool
 	var maxRounds int
 	var staleThreshold int
+	var allowedTools []string
 	var useVM bool
 	var vmName string
 	var vmJcard string
+	var providerName string
+	var providerModel string
+	var providerAPI string
 	cmd := &cobra.Command{
 		Use:   "run [-- command ...]",
 		Short: "Run sweeper against target directory",
@@ -42,15 +47,23 @@ Examples:
 			if clamped != concurrency {
 				fmt.Printf("Concurrency clamped to %d (max %d)\n", clamped, config.MaxConcurrency)
 			}
+			tools := append([]string{}, config.DefaultAllowedTools...)
+			if len(allowedTools) > 0 {
+				tools = append(tools, allowedTools...)
+			}
 			cfg := config.Config{
 				TargetDir:      targetDir,
 				Concurrency:    clamped,
 				RateLimit:      rateLimit,
+				AllowedTools:   tools,
 				TelemetryDir:   ".sweeper/telemetry",
 				DryRun:         dryRun,
 				NoTapes:        noTapes,
 				MaxRounds:      maxRounds,
 				StaleThreshold: staleThreshold,
+				Provider:       providerName,
+				ProviderModel:  providerModel,
+				ProviderAPI:    providerAPI,
 			}
 
 			piped := isPiped()
@@ -91,6 +104,17 @@ Examples:
 			cfg.VMName = vmName
 			cfg.VMJcard = vmJcard
 
+			// Validate: --vm is only compatible with CLI providers.
+			if useVM {
+				p, err := provider.Get(cfg.Provider)
+				if err != nil {
+					return fmt.Errorf("provider %q: %w", cfg.Provider, err)
+				}
+				if p.Kind != provider.KindCLI {
+					return fmt.Errorf("--vm is only compatible with CLI providers (got %q)", cfg.Provider)
+				}
+			}
+
 			if useVM {
 				absTarget, _ := filepath.Abs(cfg.TargetDir)
 				if cfg.VMName != "" {
@@ -127,12 +151,16 @@ Examples:
 			return nil
 		},
 	}
+	cmd.Flags().StringSliceVar(&allowedTools, "allowed-tools", nil, "additional tools for sub-agents (e.g. 'Bash(npm:*),Bash(cargo:*)')")
 	cmd.Flags().BoolVar(&dryRun, "dry-run", false, "show what would be fixed without making changes")
 	cmd.Flags().IntVar(&maxRounds, "max-rounds", 1, "maximum retry rounds (1 = single pass)")
 	cmd.Flags().IntVar(&staleThreshold, "stale-threshold", 2, "consecutive non-improving rounds before exploration mode")
 	cmd.Flags().BoolVar(&useVM, "vm", false, "boot ephemeral stereOS VM, teardown on exit")
 	cmd.Flags().StringVar(&vmName, "vm-name", "", "use existing VM by name (no managed lifecycle, implies --vm)")
 	cmd.Flags().StringVar(&vmJcard, "vm-jcard", "", "custom jcard.toml path (implies --vm)")
+	cmd.Flags().StringVar(&providerName, "provider", "claude", "AI provider (claude, codex, ollama)")
+	cmd.Flags().StringVar(&providerModel, "model", "", "model name for the provider (e.g. qwen2.5-coder:7b)")
+	cmd.Flags().StringVar(&providerAPI, "api-base", "", "API base URL for API providers (e.g. http://localhost:11434)")
 	return cmd
 }
 

pkg/agent/agent.go

@@ -11,6 +11,7 @@ import (
 	"github.com/papercomputeco/sweeper/pkg/linter"
 	"github.com/papercomputeco/sweeper/pkg/loop"
 	"github.com/papercomputeco/sweeper/pkg/planner"
+	"github.com/papercomputeco/sweeper/pkg/provider"
 	"github.com/papercomputeco/sweeper/pkg/session"
 	"github.com/papercomputeco/sweeper/pkg/tapes"
 	"github.com/papercomputeco/sweeper/pkg/telemetry"
@@ -33,12 +34,13 @@ type Summary struct {
 }
 
 type Agent struct {
-	cfg         config.Config
-	linterFn    LinterFunc
-	executor    worker.Executor
-	pub         *telemetry.Publisher
-	vm          VMManager
-	sessionPath string
+	cfg          config.Config
+	linterFn     LinterFunc
+	executor     worker.Executor
+	providerKind provider.Kind
+	pub          *telemetry.Publisher
+	vm           VMManager
+	sessionPath  string
 }
 
 type Option func(*Agent)
@@ -63,9 +65,26 @@ func New(cfg config.Config, opts ...Option) *Agent {
 	a := &Agent{
 		cfg:      cfg,
 		linterFn: defaultLinterFunc,
-		executor: worker.ClaudeExecutor,
 		pub:      telemetry.NewPublisher(cfg.TelemetryDir),
 	}
+
+	// Resolve provider from registry; fall back to Claude executor if lookup fails.
+	provName := cfg.Provider
+	if provName == "" {
+		provName = "claude"
+	}
+	if p, err := provider.Get(provName); err == nil {
+		a.providerKind = p.Kind
+		a.executor = p.NewExec(provider.Config{
+			Model:        cfg.ProviderModel,
+			APIBase:      cfg.ProviderAPI,
+			AllowedTools: cfg.AllowedTools,
+		})
+	} else {
+		a.providerKind = provider.KindCLI
+		a.executor = worker.NewClaudeExecutor(cfg.AllowedTools)
+	}
+
 	for _, opt := range opts {
 		opt(a)
 	}
@@ -171,14 +190,9 @@ func (a *Agent) runParsed(ctx context.Context, result linter.ParseResult, linter
 				Dir:    a.cfg.TargetDir,
 				Issues: ft.Issues,
 			}
-			switch strategy {
-			case loop.StrategyRetry:
-				tasks[i].Prompt = worker.BuildRetryPrompt(tasks[i], fh.LastOutput())
-			case loop.StrategyExploration:
-				tasks[i].Prompt = worker.BuildExplorationPrompt(tasks[i], fh.LastOutput())
+			tasks[i].Prompt = a.buildPrompt(tasks[i], strategy, fh.LastOutput())
+			if strategy == loop.StrategyExploration {
 				explorationAttempted[ft.File] = true
-			default:
-				tasks[i].Prompt = worker.BuildPrompt(tasks[i])
 			}
 		}
 
@@ -399,6 +413,28 @@ func (a *Agent) runRaw(ctx context.Context, result linter.ParseResult, linterNam
 	return summary, nil
 }
 
+// buildPrompt selects the appropriate prompt builder based on provider kind and strategy.
+func (a *Agent) buildPrompt(task worker.Task, strategy loop.Strategy, priorOutput string) string {
+	if a.providerKind == provider.KindAPI {
+		switch strategy {
+		case loop.StrategyRetry:
+			return worker.BuildAPIRetryPrompt(task, priorOutput)
+		case loop.StrategyExploration:
+			return worker.BuildAPIExplorationPrompt(task, priorOutput)
+		default:
+			return worker.BuildAPIPrompt(task)
+		}
+	}
+	switch strategy {
+	case loop.StrategyRetry:
+		return worker.BuildRetryPrompt(task, priorOutput)
+	case loop.StrategyExploration:
+		return worker.BuildExplorationPrompt(task, priorOutput)
+	default:
+		return worker.BuildPrompt(task)
+	}
+}
+
 func safeHistory(fh *loop.FileHistory) loop.FileHistory {
 	if fh == nil {
 		return loop.FileHistory{}