ralphctl

A ralph harness for long-running AI coding tasks — a hardened ralph loop that drives your coding agent of choice (Claude Code, GitHub Copilot CLI, OpenAI Codex CLI, or OpenCode) across one or more repositories.

"I'm helping!" — Ralph Wiggum

Note

Active development. New features and polish ship regularly. Upgrades are best-effort: install the latest version, redo your config, proceed. See Upgrading and CHANGELOG.

What is a ralph harness?

The "Ralph" technique comes from Geoffrey Huntley's Ralph Wiggum as a software engineer: point a coding agent at a task and run it in a loop until the work is done. The bare version (while :; do cat PROMPT.md | claude; done) loops blindly — it re-runs the same prompt and hopes each pass lands. ralphctl is a ralph harness around that idea: instead of blind repetition it runs a generator-evaluator loop, where one pass writes the change and a second independent pass reviews it against the task spec before the loop advances. Same loop, with a verification gate on every step. For the wider picture — what an agent harness is, and how the plan → generate → evaluate → verify loop turns one-shot prompting into a repeatable workflow — see AI Agent Harnesses: A Field Guide.

What is 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 wraps your chosen AI CLI — Claude Code, GitHub Copilot CLI, OpenAI Codex CLI, or OpenCode — in a structured harness that decomposes your work into dependency-ordered tasks, drives 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 — or works alongside you, whichever you prefer.

Quick Start

npm install -g ralphctl

Needs Node.js ≥ 24 — mise use node@24 or nvm install 24.

Install one of the supported CLIs and authenticate it:

CLI	Install	Auth
Claude Code	`npm i -g @anthropic-ai/claude-code`	Anthropic account
GitHub Copilot CLI	`npm i -g @github/copilot`	GitHub Copilot seat
OpenAI Codex CLI	`npm i -g @openai/codex`	ChatGPT / OpenAI
OpenCode	`npm i -g opencode-ai`	your own key, or none

Then confirm ralphctl can see it:

ralphctl doctor    # verifies your provider CLI is installed + authenticated — the #1 first-run failure

When doctor is green, launch:

ralphctl

That's it. The TUI launches, walks you through registering a project, refining your first ticket, generating a task plan, and kicking off implementation. Press + from the home screen to create a new sprint, press n to start a flow (refine / plan / implement / readiness / …), or open the Sprints submenu and follow its on-screen hint to pick or create a sprint. No commands to memorize.

Requirements: Node.js ≥ 24, Git, and one supported AI CLI in PATH and authenticated (OpenCode takes your own keys, or runs on its free tier with none).

Prefer the CLI for inspection + one-shot operations?

Interactive flows (refine / plan / ideate / implement / readiness / create sprint) are TUI-only. The CLI covers inspection and one-shot operations:

# Inspect projects + sprints
ralphctl project list
ralphctl sprint list
ralphctl sprint show <sprint-id>
ralphctl sprint progress <sprint-id>

# Add / inspect tickets
ralphctl ticket add --title "<title>"
ralphctl ticket list

# Manage sprint state
ralphctl sprint activate <sprint-id>
ralphctl sprint close <sprint-id>           # review → done
ralphctl sprint remove <sprint-id>

# Open a PR for the sprint branch
ralphctl create-pr --sprint <sprint-id>

# Export sprint artifacts
ralphctl export-requirements --sprint <id> --output <path>
ralphctl export-context --sprint <id> --project <id> --output <path>

# Settings
ralphctl settings show
ralphctl settings apply-preset claude-only     # or mixed / copilot-only / codex-only / opencode-only / *-economic / *-strong-gate / *-fast / *-frontier
ralphctl settings set ai.implement.generator.provider claude-code
ralphctl settings set ai.implement.generator.model    <model-id>
ralphctl settings set ai.implement.generator.effort   high
ralphctl settings set ai.implement.evaluator.provider openai-codex
ralphctl settings set ai.implement.evaluator.model    <model-id>

How It Works

flowchart LR
    A[Create sprint] --> B[Add tickets] --> C[Refine] --> D[Plan] --> E[Implement] --> F[Review] --> G[Done]

    classDef you fill:#eef2ff,stroke:#6366f1,color:#1e1b4b
    classDef ai fill:#ecfdf5,stroke:#10b981,color:#052e16
    classDef end_ fill:#f1f5f9,stroke:#94a3b8,color:#0f172a
    class A,B you
    class C,D,E,F ai
    class G end_

The first two steps are yours (blue); from Refine onward ralphctl drives (green), with approval gates where your judgement matters.

Refine is implementation-agnostic: the AI clarifies requirements with you, ticket by ticket, and flips each one from pending to approved. Plan requires every ticket approved — the AI explores the affected repos and generates a dependency-ordered task graph. Implement drives those tasks in dependency order through a generator-evaluator cycle: a second AI pass reviews each task against its spec before the harness marks it done and moves on. Independent tasks in the same dependency wave can run in parallel (opt-in) when you want a sprint to finish faster. Review closes the loop — once every task lands, the sprint enters review and you run human-steered feedback rounds: you flag what's off, the AI revises, and the sprint flips to done when you're satisfied. Opening a PR (ralphctl create-pr) is separate and optional.

The loop inside Implement is what separates a ralph harness from a bare while loop — every task passes an independent reviewer before the harness moves on:

flowchart LR
    T[Next task] --> G[Generator] --> E{Evaluator}
    E -->|pass| V{Verify}
    E -->|fail| R[Retry]
    V -->|green| D[Done]
    V -->|red| R
    R --> G
    R -.->|attempts exhausted| B[Blocked]

    classDef work fill:#ecfdf5,stroke:#10b981,color:#052e16
    classDef gate fill:#fefce8,stroke:#eab308,color:#422006
    classDef ok fill:#f1f5f9,stroke:#94a3b8,color:#0f172a
    classDef bad fill:#fef2f2,stroke:#ef4444,color:#450a0a
    class T,G,R work
    class E,V gate
    class D ok
    class B bad

Both gates send the task back, but they spend different budgets: a failed review re-runs the generator within the same attempt (up to harness.maxTurns turns), while a red verify fails the attempt outright and opens a fresh one (up to harness.maxAttempts, after which the task is flagged blocked).

Key properties:

Dependency-ordered execution — tasks run in topological order; no task starts until its blockers are done. Opt-in parallelism (concurrency.maxParallelTasks > 1) runs independent tasks within a dependency wave concurrently, each in its own git worktree folded onto one branch — default stays serial
Generator-evaluator cycle — an independent AI reviewer checks each task; if it fails, the generator gets the critique and iterates (up to harness.maxTurns turns per attempt, across at most harness.maxAttempts attempts before the task is flagged blocked)
Context persistence — sprint state, branch, progress history, and per-task context survive across sessions; interrupted runs resume automatically
Multi-repo support — one sprint can span several repositories with per-repo setup and verify scripts

For the full architectural picture see .claude/docs/ARCHITECTURE.md and .claude/docs/REQUIREMENTS.md.

Providers

ralphctl drives four AI coding CLIs. All four run every flow and are supported first-class. Pick one per flow — or mix them, say plan with one and implement with another — through a preset or per-row settings.

Provider	CLI	Install	Auth	Context file
Claude Code (`claude-code`)	`claude`	`npm i -g @anthropic-ai/claude-code`	Anthropic account	`CLAUDE.md`
GitHub Copilot CLI (`github-copilot`)	`copilot`	`npm i -g @github/copilot`	GitHub Copilot seat	`.github/copilot-instructions.md`
OpenAI Codex CLI (`openai-codex`)	`codex`	`npm i -g @openai/codex`	ChatGPT / OpenAI	`AGENTS.md`
OpenCode (`opencode`)	`opencode`	`npm i -g opencode-ai`	your own key, or none	`AGENTS.md`

Which one?

Claude Code — read-only flows deny the edit, shell and network tools at the CLI level, the finest-grained gate of the four.
GitHub Copilot CLI — no extra billing relationship if you already have a seat. Read-only flows deny the shell tool; file writes stay open, bounded by path scope.
OpenAI Codex CLI — a natural fit inside the ChatGPT/OpenAI ecosystem. Its sandbox has two modes only, so path scope is the fine-grained safety envelope.
OpenCode — vendor-neutral: it fronts 75+ providers and local runtimes on a bring-your-own-key model, so you can run a specific model, a local model, or no account at all.

On every backend the Write tool stays open by design — the harness's signals.json lands through it — so path scope (cwd + mounted roots) is always part of the safety envelope. See the provider reference for the exact mapping.

Bundled skill injection and forensic capture work on all four; only the on-disk skills directory differs (.claude/ / .github/ / .agents/ / .opencode/). Parallel execution is provider-agnostic. Claude Code has the most real-world mileage simply because it came first — the others are equally supported, with correspondingly less of it.

📖 Full provider reference → — permission mapping per backend, per-provider setup, model ids, mixing backends, and known limitations.

Hit a rough edge with any provider? Please open an issue.

One-shot configuration: ralphctl settings apply-preset <name> where <name> is one of 21 presets — standard, economic, strong-gate, fast, and frontier families, each in mixed / claude-only / copilot-only / codex-only variants, plus opencode-only.

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
Finish sprints faster (opt-in) — run independent tasks within a dependency wave in parallel, each in its own git worktree, folded back onto one sprint branch (still one PR); default stays serial, zero change
Branch per sprint — optional shared branch across every affected repo; ralphctl create-pr --sprint <id> opens a PR / MR via gh or glab when you're done
Recover from rate limits — exponential backoff and session resume keep the in-flight task's full context when the provider restarts
Separate the what from the how — AI clarifies requirements first (Refine), then generates the implementation plan (Plan), with human approval gates between
Pick up where you left off — full state persistence; interrupted Implement runs resume in-progress tasks first — the crashed attempt is settled as aborted (kept in history) and a fresh attempt opens 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
Bring your own model — four backends to choose from, one of which (OpenCode) is vendor-neutral, so the harness reaches hosted, aggregated, and local models alike

Configuration

Configure via the TUI Settings view or one-shot CLI commands.

Quickest path — apply a preset. Presets auto-seed from your detected CLIs on first run; override later with apply-preset.

All 21 presets

# Standard — flagship model per flow
ralphctl settings apply-preset mixed               # best-fit provider per flow
ralphctl settings apply-preset claude-only         # every flow on Claude Code
ralphctl settings apply-preset copilot-only        # every flow on GitHub Copilot CLI
ralphctl settings apply-preset codex-only          # every flow on OpenAI Codex CLI
ralphctl settings apply-preset opencode-only       # every flow on OpenCode's free tier (no auth)

# Economic — implement starts one tier below flagship; escalation ladder climbs only on plateau
ralphctl settings apply-preset mixed-economic
ralphctl settings apply-preset claude-economic
ralphctl settings apply-preset copilot-economic
ralphctl settings apply-preset codex-economic

# Strong-gate — cheap generator, permanently-flagship evaluator gate
ralphctl settings apply-preset mixed-strong-gate
ralphctl settings apply-preset claude-strong-gate
ralphctl settings apply-preset copilot-strong-gate
ralphctl settings apply-preset codex-strong-gate

# Fast — cheapest viable tier at low effort; plateau settles rather than escalating (escalateOnPlateau=false)
ralphctl settings apply-preset mixed-fast
ralphctl settings apply-preset claude-fast
ralphctl settings apply-preset copilot-fast
ralphctl settings apply-preset codex-fast

# Frontier — flagship everywhere at max effort
ralphctl settings apply-preset mixed-frontier
ralphctl settings apply-preset claude-frontier
ralphctl settings apply-preset copilot-frontier
ralphctl settings apply-preset codex-frontier

Twenty-one presets ship, all equally first-class — none is marked default. opencode-only sits outside the five-family grid on purpose: every free-tier model is at the same (zero) price point, so economic / frontier variants of it would differ in name only. Applying a preset stamps the entire ai section plus harness.escalateOnPlateau in one transaction (fast stamps it false so a plateau settles; all others stamp it true). On a fresh install the welcome view silently auto-seeds a preset based on which provider CLIs it detects on PATH.

Per-flow settings. Each flow carries its own {provider, model, effort?} row: refine, plan, readiness, ideate, and createPr. The implement flow instead splits into a nested generator / evaluator pair (ai.implement.generator.* and ai.implement.evaluator.*), each its own {provider, model, effort?} row. Edit individual keys with:

ralphctl settings set ai.implement.generator.provider claude-code
ralphctl settings set ai.implement.generator.model    <model-id>
ralphctl settings set ai.implement.generator.effort   high

ralphctl settings set ai.plan.provider      github-copilot
ralphctl settings set ai.plan.model         <model-id>

The selected provider's CLI must be in your PATH and authenticated. Every AI-spawning flow probes its row's CLI at launch and exits with a clear error if the binary is missing.

Tune the generator-evaluator loop (under harness):

ralphctl settings set harness.maxAttempts 2          # Cap fix attempts per task (1–10, default 3)
ralphctl settings set harness.maxTurns    8          # Generator-evaluator turns per attempt (1–10)
ralphctl settings set harness.rateLimitRetries 3     # Adapter-side 429 retries (0–10)

Run tasks in parallel (optional — default is serial):

ralphctl settings set concurrency.maxParallelTasks 3   # 1–5; 1 = serial (default), >1 = parallel git worktrees

When > 1, independent tasks within a dependency wave run concurrently — each in its own git worktree, with its own setupScript run, folded back onto the single sprint branch (still one PR per sprint). A task whose worktree setup fails is blocked on its own without stopping its siblings; if two same-wave tasks edit the same file, the second is blocked at fold time and a relaunch retries it. Dependencies are always respected — only independent tasks overlap.

Data directory

All state lives in ~/.ralphctl/ by default (settings under config/, sprints + projects under data/, advisory locks under state/). Override the root with:

export RALPHCTL_HOME="/path/to/custom/dir"

Environment variables

Variable	Default	Purpose
`RALPHCTL_HOME`	`~/.ralphctl/`	Override application root (data + config + state)
`RALPHCTL_SKIP_LEGACY_CHECK`	unset	Bypass the v0.6.x legacy-layout detector at boot
`RALPHCTL_NO_TUI`	unset	Suppress implicit interactive prompts in `implement`
`NO_COLOR`	unset	Suppress ANSI colors
`CI`	auto-detected	Suppress implicit interactive prompts in `implement`

Log verbosity is settings.logging.level (silent / debug / info / warn / error, default info), set via ralphctl settings set logging.level <level> or the TUI Settings view — not an environment variable.

Upgrading

Install the latest version, redo your config, proceed. Only the latest release is supported — there's no backporting, and upgrading is the answer to most "is this fixed?" questions.

npm install -g ralphctl@latest
ralphctl settings apply-preset <name>    # if your settings need a reset
ralphctl                                  # TUI prompts you to re-register projects if needed

If your ~/.ralphctl/ data from an older release doesn't load cleanly, back it up and start fresh:

mv ~/.ralphctl ~/.ralphctl.bak

The backup keeps your ticket bodies, plan output, and progress notes around for reference. See MIGRATION.md if you're crossing a major boundary (e.g. 0.6.x → 0.7.x) and want the longer story.

CLI Command Reference

The CLI surface is deliberately smaller than v0.6.x — interactive flows (refine / plan / ideate / implement / readiness / create sprint) stay TUI-only by design. The CLI exposes inspection + one-shot operations.

Getting Started

Command	Description
`ralphctl`	Interactive TUI (primary surface)
`ralphctl doctor`	Check environment health
`ralphctl settings show`	Print current settings
`ralphctl settings set <key> <value>`	Set a single settings key
`ralphctl settings apply-preset <name>`	Stamp the entire `ai` section — 21 presets: `standard` / `economic` / `strong-gate` / `fast` / `frontier` families, each in `mixed` / `*-only` variants, plus `opencode-only`
`ralphctl completion <shell>`	Print shell tab-completion script

Project & Sprint Inspection

Command	Description
`ralphctl project list`	List registered projects
`ralphctl project show <id>`	Show one project (incl. repositories)
`ralphctl project remove <id>`	Delete a project registration
`ralphctl sprint list`	List all sprints
`ralphctl sprint show <id>`	Show one sprint (tickets, status, branch)
`ralphctl sprint progress <id>`	Sprint progress with blocker diagnostics
`ralphctl sprint set-current <id>`	Switch the current sprint pointer
`ralphctl ticket add --title <title>`	Add a ticket to the current sprint (`--sprint`, `--description`, `--link` optional)
`ralphctl ticket list / show <id>`	Inspect tickets
`ralphctl ticket remove <id>`	Remove a ticket from a draft sprint
`ralphctl task list / show <id>`	Inspect tasks (planning generates them)
`ralphctl task unblock <id>`	Reset a blocked task to `todo`

Sprint Lifecycle

Command	Description
`ralphctl sprint activate <id>`	Flip a draft sprint to `active`
`ralphctl sprint close <id>`	Transition `review` → `done`
`ralphctl sprint remove <id>`	Delete a sprint permanently

Export & PR

Command	Description
`ralphctl export-requirements [--sprint <id>] --output <path>`	Render approved-ticket requirements to markdown
`ralphctl export-context [--sprint <id>] [--project <id>] --output <path>`	Render harness context (sprint + project + tasks) to markdown
`ralphctl create-pr --sprint <id> [--base <branch>] [--draft]`	Open a PR/MR via `gh` or `glab`, persist the URL on the sprint

Maintenance

Command	Description
`ralphctl runs list [--flow <name>]`	List per-run forensic artifacts grouped by flow
`ralphctl runs prune [--older-than 7d] [--keep-last <n>] [--flow <name>] [--dry-run] [-y]`	Delete per-run forensic artifacts

Run ralphctl <command> --help for flag-level detail.

Documentation

Resource	Description
Architecture	Data models, harness loop, file storage, error reference
Providers	Per-backend setup, permission mapping, model ids, limits
Adding a provider	Extension guide: wire a new AI CLI into the harness
Requirements	Acceptance criteria and feature checklist
Contributing	Dev setup, code style, PR process
Migration	Per-version upgrade context for big version jumps
Changelog	Version history

From the author (Lukas Grigis): Building ralphctl (backstory) | From task CLI to ralph harness (evaluator deep-dive) | The harness era caught up (the field converges on the harness bet)

Further reading: AI Agent Harnesses: A Field Guide — Lukas Grigis | Harness Engineering for Coding Agent Users — Birgitta Böckeler, martinfowler.com (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.

Name		Name	Last commit message	Last commit date
Latest commit History 1,381 Commits
.claude		.claude
.github		.github
.husky		.husky
bin		bin
docs		docs
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MIGRATION.md		MIGRATION.md
README.md		README.md
SECURITY.md		SECURITY.md
THIRD-PARTY-NOTICES.md		THIRD-PARTY-NOTICES.md
eslint.config.ts		eslint.config.ts
knip.json		knip.json
mise.toml		mise.toml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

ralphctl

What is a ralph harness?

What is ralphctl?

Quick Start

How It Works

Providers

Features

Configuration

Data directory

Environment variables

Upgrading

Getting Started

Project & Sprint Inspection

Sprint Lifecycle

Export & PR

Maintenance

Documentation

Development

Contributing

Security

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

ralphctl

What is a ralph harness?

What is ralphctl?

Quick Start

How It Works

Providers

Features

Configuration

Data directory

Environment variables

Upgrading

Getting Started

Project & Sprint Inspection

Sprint Lifecycle

Export & PR

Maintenance

Documentation

Development

Contributing

Security

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages