Ralph

Ralph is a control plane for autonomous AI coding agents. It manages the full lifecycle of automated code work — from defining what needs to be done, to executing it, to verifying the result.

Stories are the core unit. Each story has a title, scope, acceptance criteria, verification commands, owned file paths, and dependency chains to other stories. Stories live inside backlogs, which can be imported from JSON or built interactively. When a run starts, Ralph walks the backlog and feeds stories to the agent in dependency order.

Runs execute locally or in the cloud. Local agents poll the server for queued runs and execute in your project directory — start a run from your phone and the agent picks it up. Cloud execution submits runs to Google Cloud Batch, which clones the repo, checks out the right ref, and runs the agent in an isolated container.

The worker layer handles the mechanics: clone-run clones a repo and claims work, execute-run works from an existing checkout. Both support configurable Git auth, repo subdirectories, and ref targeting.

Runtime profiles configure agent behavior per repo — max concurrency, lease durations, heartbeat and renewal intervals, poll frequency. Profiles are stored in .ralph.yaml alongside your code.

Live log streaming shows agent output in real time. Run events track state transitions. Audit logs record every action across the workspace. Stats aggregate run counts, story completion rates, and per-user activity with time-series breakdowns.

Ralph integrates with PAC for backlog-driven automation — PAC tasks can be routed to Ralph for autonomous execution. The web dashboard at ralph.happenings.social provides workspace administration, run history, and story management.

Built with Go, ConnectRPC, and Protocol Buffers. Server deployed on Cloud Run, storage on PostgreSQL with sqlc. CLI authenticates via browser login or mobile QR pairing and self-updates.