ralphctl

Agent harness for long-running AI coding tasks —
orchestrates Claude Code & GitHub Copilot
across repositories.

"I'm helping!" — Ralph Wiggum

[!NOTE]
Active development — new features and polish ship regularly. Setup is quick, so upgrading is low-friction. See
CHANGELOG.

Upgrading from 0.6.x to 0.7.0

[!IMPORTANT]
0.7.0 is a structural rewrite. Internal architecture, on-disk schema, data root, and
several CLI commands all changed. There is no automatic migration from 0.6.x — sprints,
projects, and settings written by 0.6.x will not be read by 0.7.0.

Before upgrading

1. Back up your 0.6.x data so it's safe to fall back to:

   mv ~/.ralphctl ~/.ralphctl.0.6-backup
   

2. Install 0.7.0:

   npm install -g [email protected]
   

3. Launch the TUI and re-register your projects:

   ralphctl
   

4. (Optional) Re-create sprints by hand from the backup — ~/.ralphctl.0.6-backup/data/sprints/<id>/
   still holds the original ticket bodies, plan output, and progress notes for reference.

What changed

• Data root moved. v0.7.0 stores everything under ~/.ralphctl-v2/ (override with
  RALPHCTL_HOME=<absolute-path>). Your 0.6.x data at ~/.ralphctl/ is left untouched.
• On-disk schema split. Each sprint now spans three files — sprint.json (planning),
  execution.json (branch / PR / setup audit), tasks.json (the task list) — instead of the
  single 0.6.x sprint.json. The 0.6.x layout will not parse.
• settings.json schema changed. Per-flow model selection replaces the single global
  model; each chain (refine, plan, implement, ideate, readiness) picks its own.
  0.6.x settings files are rejected on read — re-run ralphctl settings to reconfigure.
• CLI surface intentionally smaller. These commands were removed in favour of the TUI:
  sprint feedback / edit, ticket approve / edit, project repo add / remove,
  all task add / edit / edit-status / remove, and sessions list / attach / detach / kill.
  If you scripted any of these, switch to the interactive TUI or to ralphctl sprint show <id>
  / the relevant flow command.
• OpenAI Codex provider added alongside Claude Code and GitHub Copilot — pick via
  ralphctl settings.

See CHANGELOG.md for the full list, including non-breaking
improvements (cross-project sprint lock, idle-stdout watchdog, resume-aborted runs, persistent
<sprintDir>/chain.log, exponential rate-limit backoff).

Why ralphctl?

AI coding agents are powerful but lose context on long tasks, need babysitting when things break, and have no way to
coordinate changes across multiple repositories. RalphCTL decomposes your work into dependency-ordered tasks, runs each
one through a generator-evaluator loop that
catches issues before moving on, and persists context across sessions so nothing gets lost. You describe what to build —
ralphctl handles the rest.

How It Works

  You describe what to build           ralphctl handles the rest
  ─────────────────────────           ─────────────────────────────────
  ┌──────────┐   ┌──────────┐        ┌────────┐   ┌──────┐   ┌─────────┐
  │  Create  │──>│   Add    │───────>│ Refine │──>│ Plan │──>│ Execute │
  │  Sprint  │   │ Tickets  │        │ (WHAT) │   │(HOW) │   │  Loop   │
  └──────────┘   └──────────┘        └────────┘   └──────┘   └─────────┘
                                          │            │           │
                                     AI clarifies  AI generates  AI implements
                                     requirements  task graph    + AI reviews
                                     with you      from specs    each task

• Dependency-ordered execution — tasks run strictly one at a time in topological order; the evaluator's read-only
  git status check catches dirty trees so work doesn't compound on a broken state
• Generator-evaluator cycle — an independent AI reviewer checks each task against its spec; if it fails, the
  generator gets feedback and iterates
• Context persistence — sprint state, progress history, and task context survive across sessions; interrupted work
  resumes where it left off

Quick Start

npm install -g ralphctl
ralphctl

That's it. Launches the interactive TUI — walks you through project setup, ticket refinement, task planning, and
execution. No commands to memorize.

Requires Node.js >= 24, Git, and
either Claude CLI
or GitHub Copilot CLI installed and authenticated.

# 1. Register a project (points to your repo)
ralphctl project add

# 2. Create a sprint
ralphctl sprint create --name "my-first-sprint"

# 3. Add a ticket
ralphctl ticket add --project my-app --title "Add user authentication"

# 4. Let AI refine requirements, plan tasks, and execute
ralphctl sprint refine
ralphctl sprint plan
ralphctl sprint start

Features

• Break big tickets into small tasks — dependency-ordered so they execute in the right sequence
• Catch mistakes before they compound — independent AI review after each task, iterating until quality passes or
  budget is exhausted
• Coordinate across repositories — one sprint can span multiple repos with automatic dependency tracking
• Branch per sprint — optional shared branch across every affected repo, with sprint close --create-pr to open
  pull requests when you're done
• Recover from rate limits — automatic session resume across rate-limit pauses keeps the in-flight task's full
  context when the provider restarts
• Separate the what from the how — AI clarifies requirements first, then generates implementation tasks, with human
  approval gates
• Pick up where you left off — full state persistence across sessions; interrupted work resumes automatically
• Pair or let it run — work alongside your AI agent interactively, or let it execute unattended
• Zero-memorization start — run ralphctl with no args for a guided menu

Configuration

RalphCTL supports Claude Code and GitHub Copilot as AI backends.

ralphctl config set provider claude      # Use Claude Code
ralphctl config set provider copilot     # Use GitHub Copilot

Auto-prompts on first AI command if not set. Both CLIs must be in your PATH and authenticated.

Tune the generator-evaluator loop:

ralphctl config set evaluationIterations 2   # Up to 2 fix attempts per task (default: 1)
ralphctl config set evaluationIterations 0   # Disable evaluation entirely

sprint start --no-evaluate skips evaluation for a single run without touching the global setting.

Data Directory

All data lives in ~/.ralphctl/ by default. Override with:

export RALPHCTL_ROOT="/path/to/custom/data-dir"

Getting Started

Project & Sprint Setup

AI-Assisted Planning

Execution & Monitoring

Run ralphctl <command> --help for details on any command.

Documentation

Blog posts: Building ralphctl (backstory) | From task CLI to agent harness (evaluator deep-dive)

Further reading: Harness Engineering for Coding Agent Users — Martin Fowler (April 2026) | Harness Design for Long-Running Application Development — Anthropic Engineering

Development

git clone https://github.com/lukas-grigis/ralphctl.git
cd ralphctl
pnpm install
pnpm dev --help          # Run CLI in dev mode (tsx, no build needed)
pnpm build               # Compile for npm distribution (tsup)
pnpm typecheck           # Type check
pnpm test                # Run tests
pnpm lint                # Lint

Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change.

See CONTRIBUTING.md for the full guide — dev setup, code style, PR process, and releasing.

This project follows the Contributor Covenant code of conduct.

Security

To report a vulnerability,
use GitHub's private reporting.
See SECURITY.md for details.

License

MIT — see LICENSE for details.