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.5.x to 0.6.0

The rewrite changes the on-disk layout under ~/.ralphctl/. Existing 0.5.x data is not migrated automatically. Before upgrading:

1. Back up your existing data: mv ~/.ralphctl ~/.ralphctl.0.5-backup
2. Install 0.6.0 (pnpm install [email protected] or via your package manager)
3. Run ralphctl project add to register your projects in the new layout
4. (Optional) Re-create sprints from your backup as needed

ralphctl will detect a legacy layout on first launch and refuse to start until you back up + reset, with instructions printed.

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.

| Feature | Claude Code | GitHub Copilot | | --------------------------- | ------------------------------------ | -------------------------------------------------------------------- | | Status | GA | Public preview | | Headless execution | -p --output-format json | -p --output-format json --autopilot --no-ask-user | | Session IDs | In JSON output (session_id) | In JSON output (session_id), --share file as fallback | | Session resume (--resume) | Full support | Full support | | Per-tool permissions | Settings files + --permission-mode | --allow-all-tools (all-or-nothing by default) | | Fine-grained tool control | allow/deny in settings files | --allow-tool, --deny-tool flags (not yet used) | | Rate limit detection | Validated patterns | Borrowed from Claude — not yet validated against real Copilot errors |

Data Directory

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

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

Getting Started

| Command | Description | | ------------------------------------------------ | ----------------------------------- | | ralphctl | Interactive menu mode (recommended) | | ralphctl doctor | Check environment health | | ralphctl config set provider <claude\|copilot> | Set AI provider | | ralphctl config show | Show current configuration | | ralphctl completion install | Enable shell tab-completion |

Project & Sprint Setup

| Command | Description | | ----------------------------- | -------------------------------- | | ralphctl project add | Register a project and its repos | | ralphctl sprint create | Create a new sprint (draft) | | ralphctl sprint list | List all sprints | | ralphctl sprint show | Show current sprint details | | ralphctl sprint set-current | Switch the current sprint | | ralphctl ticket add | Add a work item to a sprint |

AI-Assisted Planning

| Command | Description | | ------------------------------ | --------------------------------------- | | ralphctl sprint refine | Clarify requirements with AI (WHAT) | | ralphctl sprint plan | Generate tasks from requirements (HOW) | | ralphctl sprint ideate | Quick single-session refine + plan | | ralphctl sprint requirements | Export refined requirements to markdown |

Execution & Monitoring

| Command | Description | | -------------------------- | ------------------------------------------------------ | | ralphctl sprint start | Execute tasks with AI (--branch for a sprint branch) | | ralphctl sprint progress | Sprint progress with blocker / stale-task diagnostics | | ralphctl task list | List tasks in the current sprint | | ralphctl sprint close | Close an active sprint (--create-pr for PRs) | | ralphctl sprint remove | Delete a sprint permanently |

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

Documentation

| Resource | Description | | ---------------------------------------------- | ------------------------------------------ | | Architecture | Data models, file storage, error reference | | Requirements | Acceptance criteria and feature checklist | | Contributing | Dev setup, code style, PR process | | 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.