feat(run): swarm mode — parallel multi-agent implementation#155
Merged
feat(run): swarm mode — parallel multi-agent implementation#155
Conversation
Swarm mode (`bmalph run --swarm [N]`) spawns N Ralph loops in isolated git worktrees, each working on different epics simultaneously. Stories are partitioned by epic using greedy bin-packing, and branches are merged back sequentially after all workers complete. Key features: - Epic-aware fix plan parser with raw markdown block preservation - Greedy bin-packing partitioner for balanced story distribution - Git worktree lifecycle management with orphan cleanup - Sequential merger with .ralph/ exclusion and fix plan rebuild - Clean working tree validation, detached HEAD rejection - Staggered worker starts to avoid API rate limit clustering - Git gc disabled per-worker (GIT_CONFIG env vars) to prevent lock contention - Worker exit code tracking: only successful workers are merged - Conflict branch preservation via .swarm/.conflict-branches - Signal handler with idempotency guard and .catch/.finally Safety: PLATFORM_DRIVER cannot be overridden via SpawnOptions.env (spread order), .conflict-branches validated against swarm/worker-\d+ pattern, atomicWriteFile for fix plan writes. Includes 51 unit/integration tests and 10 E2E tests covering validation error paths, CLI parsing, worktree lifecycle, merge correctness, conflict handling, and orphan cleanup.
Add --swarm [count] to CLI reference table and features list, expand CLAUDE.md command table, add run options and "Swarm Mode" section to README, and add a full Swarm Mode section to RALPH-REFERENCE.md covering partitioning, worktrees, merging, conflict handling, and interaction with circuit breaker, sessions, and code review.
Terminal UI for swarm mode showing all workers simultaneously: - Summary row per worker with status icon, epic names, loop count, progress bar, and circuit breaker state - Number keys (1-N) focus a worker to show full detail panels (loop, CB, stories, analysis, review, logs — reuses existing renderers) - q/s/d key bindings for quit prompt (stop all / detach all / cancel) - Auto-resolves when all workers exit; 2s refresh interval Parameterized renderHeader() title to allow "RALPH SWARM" header. Dashboard is active by default; disable with --no-dashboard.
- Dashboard "stop" action now calls stop() (matching "detach" path), preventing a latent hang if watcher doesn't tick - CLI help text includes max workers: "(default: 2, max: 6)" - README swarm requirements adds "not on detached HEAD" - CLAUDE.md swarm entry includes default/max workers - RALPH-REFERENCE.md documents default rate limit base (100)
- Remove unnecessary ?? on exhaustive Record lookups (no-unnecessary-condition) - Make resolveStartBranch and removeWorktree sync (require-await) - Update cleanupMergedWorkers to sync (no async without await) - Use process.stdout.columns || 80 instead of ?? (lint compatibility) - Suppress no-unnecessary-condition on signal handler guard (concurrent mutation) - Use else instead of else-if on exhaustive union (MergeStatus) - Remove unused readFile import from orchestrator test - Fix Windows path separator in worktree test (join instead of hardcoded /) - Update test assertions for sync function signatures
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
bmalph run --swarm [N]) spawns N Ralph loops in isolated git worktrees, each working on different epics simultaneously.ralph/exclusion — only successfully completed workers are merged, fix plan rebuilt from combined completionsNew modules (
src/swarm/)types.tsfix-plan-parser.tspartitioner.tsworktree.tsmerger.ts.ralph/exclusion and fix plan rebuildorchestrator.tsrun.tsdashboard.tsModified files
src/cli.ts—--swarm [count]optionsrc/commands/run.ts— swarm routing +parseSwarmCount()src/run/ralph-process.ts—envfield onSpawnOptionssrc/utils/constants.ts— swarm constants +.swarm/in gitignore entriessrc/watch/renderer.ts— parameterizedrenderHeader()titleTest coverage
tests/swarm/tests/e2e/swarm.e2e.test.tsTest plan
npx tsc --noEmit— types cleannpx vitest run— 1788 tests passingnpx vitest run --config vitest.config.e2e.ts— 151 E2E tests passingnpx eslint src/ tests/— 0 errorsbmalph run --swarm 2on a project with >= 2 epics