GitHub - lukas-grigis/ralphctl: Agent harness for long-running AI coding tasks — orchestrates Claude Code & GitHub Copilot across repositories 🍩

Agent harness for long-running AI coding tasks — orchestrates Claude Code across repositories, with GitHub Copilot and OpenAI Codex available in preview.

"I'm helping!" — Ralph Wiggum

Note

Active development. New features and polish ship regularly. The 0.8.x line continues a burst of structural changes — thanks for sticking with us through it. Upgrades are simple: install the latest version, redo your config, proceed. See Upgrading and CHANGELOG.

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 — currently Claude Code — 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

Install Claude Code (or a preview provider — see below), authenticate it, then:

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.

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
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
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

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

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 one at a time through a generator-evaluator cycle: a second AI pass reviews each task against its spec before the harness marks it done and moves to the next.

Key properties:

Dependency-ordered execution — tasks run strictly one at a time in topological order; no task starts until its blockers are done
Generator-evaluator cycle — an independent AI reviewer checks each task; if it fails, the generator gets the critique and iterates (up to harness.maxAttempts tries 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.

Provider Status

Important

Not all three AI providers are equally production-ready inside ralphctl.

Provider	Status	Headless flag	Native context file
Claude Code (`claude-code`)	Stable — primary verified provider	`--permission-mode bypassPermissions` + per-tool deny list	`CLAUDE.md` at repo root
GitHub Copilot CLI (`github-copilot`)	Preview — not officially verified by us	`--autopilot --allow-all` + `--max-autopilot-continues=200`	`.github/copilot-instructions.md`
OpenAI Codex (`openai-codex`)	Preview — not officially verified by us	`-s workspace-write` (topology-scoped)	`AGENTS.md`

"Preview" means the integration exists and the TUI lets you select it, but end-to-end harness behaviour against those providers has not been formally verified. Copilot and Codex no-op some features (bundled skill injection, bodyFile forensic artifacts). Codex cannot fine-grained-deny edits on existing repo files — its sandbox modes are binary, so path scope (cwd + --add-dir) is the only safety envelope. If you hit a rough edge on a preview provider, please open an issue.

One-shot configuration for any provider: ralphctl settings apply-preset <name> where <name> is mixed, claude-only, copilot-only, or codex-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
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 reset in-progress tasks and re-enter the queue on next launch
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

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

Quickest path — apply a preset:

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
ralphctl settings apply-preset codex-only     # every flow on OpenAI Codex

A preset stamps the entire ai section in one shot. None is marked default; 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)

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 (`mixed` / `claude-only` / `copilot-only` / `codex-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`	Add a ticket to the current sprint
`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, file storage, error reference
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

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.

Name		Name	Last commit message	Last commit date
Latest commit History 947 Commits
.claude		.claude
.github		.github
.husky		.husky
bin		bin
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
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
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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

What is ralphctl?

Quick Start

How It Works

Provider Status

Features

Configuration

Data directory

Environment variables

Upgrading

Getting Started

Project & Sprint Inspection

Sprint Lifecycle

Export & PR

Maintenance

Documentation

Development

Contributing

Security

License

About

Uh oh!

Releases 38

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

What is ralphctl?

Quick Start

How It Works

Provider Status

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

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 38

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages