🍩 ██████╗  █████╗ ██╗     ██████╗ ██╗  ██╗ ██████╗████████╗██╗     🍩
     ██╔══██╗██╔══██╗██║     ██╔══██╗██║  ██║██╔════╝╚══██╔══╝██║
     ██████╔╝███████║██║     ██████╔╝███████║██║        ██║   ██║
     ██╔══██╗██╔══██║██║     ██╔═══╝ ██╔══██║██║        ██║   ██║
     ██║  ██║██║  ██║███████╗██║     ██║  ██║╚██████╗   ██║   ███████╗
     ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝  ╚═╝ ╚═════╝   ╚═╝   ╚══════╝

Sprint and task management CLI for AI-assisted coding with Claude Code or GitHub Copilot.

"I'm helping!" — Ralph Wiggum

[!NOTE] Early access. RalphCTL is under active development. Things work, but expect rough edges and breaking changes before 1.0. Read the blog post for the backstory.

You write tickets, your AI buddy (Claude or Copilot) refines the requirements, then breaks them into tasks and executes them. RalphCTL keeps track of the state so nothing gets lost between sessions. Ralph Wiggum personality included because why not.

Install

npm install -g ralphctl

This installs the ralphctl command globally.

Prerequisites

• Node.js >= 24.0.0
• Git
• Either Claude CLI or GitHub Copilot CLI installed and authenticated

2-Minute Quick Start

# 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

Or just run ralphctl with no arguments for an interactive menu that walks you through everything.

Table of Contents

• Features
• CLI Overview
• AI Provider Configuration
• Documentation
• Development
• Contributing
• License

Features

• Two-phase planning — clarify requirements first (what), then generate tasks (how), with a human approval gate between them
• Multi-repo sprints — a single sprint can track tickets across multiple repositories
• Task dependencies — blockedBy references with topological sort; tasks run in the right order
• Interactive or headless — pair with Claude in a session, or let it run unattended
• Sprint lifecycle — state machine (draft -> active -> closed) with file locking for concurrent safety
• Parallel execution — one task per repo at a time, with automatic rate limit backoff and session resume
• Menu mode — run ralphctl with no arguments for an interactive menu

CLI Overview

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 switch | Quick sprint switcher | | 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 | | ralphctl sprint health | Diagnose blockers and stale tasks | | ralphctl dashboard | Sprint overview with progress bar | | ralphctl task list | List tasks in the current sprint | | ralphctl task next | Show the next unblocked task | | ralphctl sprint close | Close an active sprint | | ralphctl sprint delete | Delete a sprint permanently |

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

AI Provider Configuration

RalphCTL supports Claude Code and GitHub Copilot as AI backends. Both use the same prompt templates and workflow.

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.

Provider Differences

| Feature | Claude Code | GitHub Copilot | | --------------------------- | ------------------------------------ | -------------------------------------------------------------------- | | Status | GA | Public preview | | Headless execution | -p --output-format json | -p -s --autopilot --no-ask-user | | Session IDs | In JSON output (session_id) | Captured via --share output file | | Session resume (--resume) | Full support | Supported when session ID is available | | 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 |

Documentation

| Document | Description | | ----------------------------------------------------------- | ---------------------------------------------- | | REQUIREMENTS.md | Acceptance criteria and feature requirements | | ARCHITECTURE.md | Data models, file storage, and error reference | | CLAUDE.md | Developer guide and Claude Code project config | | CONTRIBUTING.md | How to contribute | | CHANGELOG.md | Version history | | Blog post | Background and motivation |

Data Directory

RalphCTL stores all data in ~/.ralphctl/ by default. Override with RALPHCTL_ROOT:

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

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.