How advaith-1212/railwarden works
RailWarden is a deterministic control plane for multi-agent software work: approved plans become dependency-aware packages, workers implement them in isolated Git worktrees, and validation, review, and integration gates determine completion. The controller coordinates execution; file-backed runtime state and events preserve facts across failures. The README documents the major lifecycle and supporting interfaces. Some subsystem paths and interactions are represented at directory level because their implementation was not excerpted.
Main entry points: controller.py Execution Controller · main.py CLI · pipeline.py Plan Pipeline · manager.py Integration Gates
Components 22
User Interfaces
- CLI
src/railwarden/cli/main.py - MCP Server
src/railwarden/mcp/server.py - Dashboard
src/railwarden/engine/dashboard.py - Kanban View
src/railwarden/hermes/kanban.py - tmux Sessions
src/railwarden/tmux/session.py - Hermes Integration
src/railwarden/hermes/profile.py
Planning and Scheduling
- Plan Pipeline
src/railwarden/planning/pipeline.py - Package Scheduler
src/railwarden/scheduler/classifier.py - Project Contracts
src/railwarden/config/models.py
Worker Execution
- Execution Controller
src/railwarden/engine/controller.py - Git Worktrees
src/railwarden/provisioning/worktrees.py - Git Operations
src/railwarden/git.py - Process Supervisor
src/railwarden/processes/supervisor.py - Provider Adapters
src/railwarden/providers/adapters.py
Runtime State
- Task State
src/railwarden/runtime/tasks.py - Event Log
src/railwarden/runtime/events.py - Recovery State
src/railwarden/runtime/checkpoints.py - Worker Results
src/railwarden/runtime/results.py
Validation and Integration
- Mechanical Validation
src/railwarden/validation/package.py - Review Gates
src/railwarden/validation/review.py - Integration Gates
src/railwarden/integration/manager.py
Other components
- Developer
Connections 26
- Developer → CLI: invokes
README.md - Developer → MCP Server: uses tools
README.md - CLI → Execution Controller: controls execution
src/railwarden/cli/main.py - MCP Server → Execution Controller: calls
src/railwarden/mcp/server.py - Execution Controller → Plan Pipeline: loads plans
src/railwarden/engine/controller.py - Plan Pipeline → Project Contracts: builds packages
src/railwarden/planning/pipeline.py - Plan Pipeline → Package Scheduler: defines dependencies
README.md - Execution Controller → Package Scheduler: classifies packages
src/railwarden/engine/controller.py - Execution Controller → Task State: updates tasks
src/railwarden/engine/controller.py - Execution Controller → Git Worktrees: provisions worktrees
src/railwarden/engine/controller.py - Git Worktrees → Git Operations: runs Git
src/railwarden/provisioning/worktrees.py - Execution Controller → Process Supervisor: supervises workers
src/railwarden/engine/controller.py - Process Supervisor → Provider Adapters: launches adapters
src/railwarden/providers/adapters.py - Execution Controller → Worker Results: normalizes results
src/railwarden/engine/controller.py - Execution Controller → Mechanical Validation: validates packages
README.md - Execution Controller → Review Gates: checks readiness
README.md - Execution Controller → Recovery State: records checkpoints
README.md - Execution Controller → Event Log: records events
README.md - Execution Controller → Integration Gates: requests integration
README.md - Integration Gates → Git Operations: merges branches
src/railwarden/integration/manager.py - Integration Gates → Mechanical Validation: runs post-merge checks
src/railwarden/integration/manager.py - CLI → Dashboard: presents status
src/railwarden/cli/main.py - Hermes Integration → Kanban View: supports board view
README.md - tmux Sessions → Process Supervisor: manages worker panes
src/railwarden/tmux/session.py - Hermes Integration → Execution Controller: supervises workflow
README.md - Execution Controller → Recovery State: hands off failures
README.md