{"id":47659692,"url":"https://github.com/lukas-grigis/ralphctl","last_synced_at":"2026-04-22T06:09:50.421Z","repository":{"id":342802868,"uuid":"1150908105","full_name":"lukas-grigis/ralphctl","owner":"lukas-grigis","description":"Agent harness for long-running AI coding tasks — orchestrates Claude Code \u0026 GitHub Copilot across repositories 🍩","archived":false,"fork":false,"pushed_at":"2026-04-17T19:46:33.000Z","size":2346,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T21:25:31.895Z","etag":null,"topics":["agent-harness","ai","ai-coding","anthropic","claude","claude-code","cli","copilot","developer-tools","generator-evaluator","github-copilot","long-running-agents","sprint-management","task-management","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/ralphctl","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lukas-grigis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-05T20:42:40.000Z","updated_at":"2026-04-17T19:44:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"bf9a45d0-7aac-4701-9f53-f27311fc82f1","html_url":"https://github.com/lukas-grigis/ralphctl","commit_stats":null,"previous_names":["lukas-grigis/ralphctl"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/lukas-grigis/ralphctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukas-grigis%2Fralphctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukas-grigis%2Fralphctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukas-grigis%2Fralphctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukas-grigis%2Fralphctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lukas-grigis","download_url":"https://codeload.github.com/lukas-grigis/ralphctl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukas-grigis%2Fralphctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32123638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T00:31:26.853Z","status":"online","status_checked_at":"2026-04-22T02:00:05.693Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-harness","ai","ai-coding","anthropic","claude","claude-code","cli","copilot","developer-tools","generator-evaluator","github-copilot","long-running-agents","sprint-management","task-management","typescript"],"created_at":"2026-04-02T10:49:57.374Z","updated_at":"2026-04-22T06:09:50.416Z","avatar_url":"https://github.com/lukas-grigis.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm version](https://img.shields.io/npm/v/ralphctl?style=flat\u0026logo=npm\u0026logoColor=white\u0026color=cb3837)](https://www.npmjs.com/package/ralphctl)\n[![npm downloads](https://img.shields.io/npm/dm/ralphctl?style=flat\u0026logo=npm\u0026logoColor=white\u0026color=cb3837)](https://www.npmjs.com/package/ralphctl)\n[![CI](https://github.com/lukas-grigis/ralphctl/actions/workflows/ci.yml/badge.svg)](https://github.com/lukas-grigis/ralphctl/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat\u0026logo=opensourceinitiative\u0026logoColor=white)](./LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6?style=flat\u0026logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/node-%E2%89%A5_24-5fa04e?style=flat\u0026logo=nodedotjs\u0026logoColor=white)](https://nodejs.org/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat\u0026logo=git\u0026logoColor=white)](./CONTRIBUTING.md)\n[![Claude Code](https://img.shields.io/badge/Claude_Code-191919?style=flat\u0026logo=anthropic\u0026logoColor=white)](https://docs.anthropic.com/en/docs/claude-code)\n[![GitHub Copilot](https://img.shields.io/badge/GitHub_Copilot-000?style=flat\u0026logo=githubcopilot\u0026logoColor=white)](https://docs.github.com/en/copilot/github-copilot-in-the-cli)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./.github/assets/home.png\" alt=\"ralphctl home screen — Ralph donut banner, sprint pipeline, keybinding footer\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n**Agent harness for long-running AI coding tasks —\norchestrates [Claude Code](https://docs.anthropic.com/en/docs/claude-code) \u0026 [GitHub Copilot](https://docs.github.com/en/copilot/github-copilot-in-the-cli)\nacross repositories.**\n\n\u003e _\"I'm helping!\"_ — Ralph Wiggum\n\n\u003e [!NOTE]\n\u003e **Active development** — new features and polish ship regularly. Setup is quick, so upgrading is low-friction. See\n\u003e [CHANGELOG](./CHANGELOG.md).\n\n---\n\n## Why ralphctl?\n\nAI coding agents are powerful but lose context on long tasks, need babysitting when things break, and have no way to\ncoordinate changes across multiple repositories. RalphCTL decomposes your work into dependency-ordered tasks, runs each\none through a [generator-evaluator loop](https://www.anthropic.com/engineering/harness-design-long-running-apps) that\ncatches issues before moving on, and persists context across sessions so nothing gets lost. You describe what to build —\nralphctl handles the rest.\n\n---\n\n## How It Works\n\n```\n  You describe what to build           ralphctl handles the rest\n  ─────────────────────────           ─────────────────────────────────\n  ┌──────────┐   ┌──────────┐        ┌────────┐   ┌──────┐   ┌─────────┐\n  │  Create  │──\u003e│   Add    │───────\u003e│ Refine │──\u003e│ Plan │──\u003e│ Execute │\n  │  Sprint  │   │ Tickets  │        │ (WHAT) │   │(HOW) │   │  Loop   │\n  └──────────┘   └──────────┘        └────────┘   └──────┘   └─────────┘\n                                          │            │           │\n                                     AI clarifies  AI generates  AI implements\n                                     requirements  task graph    + AI reviews\n                                     with you      from specs    each task\n```\n\n- **Dependency-ordered execution** — tasks run in the right sequence, one per repo at a time, with parallel execution\n  where possible\n- **Generator-evaluator cycle** — an independent AI reviewer checks each task against its spec; if it fails, the\n  generator gets feedback and iterates\n- **Context persistence** — sprint state, progress history, and task context survive across sessions; interrupted work\n  resumes where it left off\n\n---\n\n## Quick Start\n\n```bash\nnpm install -g ralphctl\nralphctl\n```\n\nThat's it. Launches the interactive TUI — walks you through project setup, ticket refinement, task planning, and\nexecution. No commands to memorize.\n\nRequires [Node.js](https://nodejs.org/) \u003e= 24, [Git](https://git-scm.com/), and\neither [Claude CLI](https://docs.anthropic.com/en/docs/claude-code)\nor [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) installed and authenticated.\n\n\u003cdetails\u003e\n\u003csummary\u003ePrefer explicit commands?\u003c/summary\u003e\n\n```bash\n# 1. Register a project (points to your repo)\nralphctl project add\n\n# 2. Create a sprint\nralphctl sprint create --name \"my-first-sprint\"\n\n# 3. Add a ticket\nralphctl ticket add --project my-app --title \"Add user authentication\"\n\n# 4. Let AI refine requirements, plan tasks, and execute\nralphctl sprint refine\nralphctl sprint plan\nralphctl sprint start\n```\n\n\u003c/details\u003e\n\n---\n\n## Features\n\n- **Break big tickets into small tasks** — dependency-ordered so they execute in the right sequence\n- **Catch mistakes before they compound** — independent AI review after each task, iterating until quality passes or\n  budget is exhausted\n- **Coordinate across repositories** — one sprint can span multiple repos with automatic dependency tracking\n- **Branch per sprint** — optional shared branch across every affected repo, with `sprint close --create-pr` to open\n  pull requests when you're done\n- **Run tasks in parallel** — one per repo, with rate-limit backoff and automatic session resume\n- **Separate the what from the how** — AI clarifies requirements first, then generates implementation tasks, with human\n  approval gates\n- **Pick up where you left off** — full state persistence across sessions; interrupted work resumes automatically\n- **Pair or let it run** — work alongside your AI agent interactively, or let it execute unattended\n- **Zero-memorization start** — run `ralphctl` with no args for a guided menu\n\n---\n\n## Configuration\n\nRalphCTL supports **Claude Code** and **GitHub Copilot** as AI backends.\n\n```bash\nralphctl config set provider claude      # Use Claude Code\nralphctl config set provider copilot     # Use GitHub Copilot\n```\n\nAuto-prompts on first AI command if not set. Both CLIs must be in your PATH and authenticated.\n\nTune the generator-evaluator loop:\n\n```bash\nralphctl config set evaluationIterations 2   # Up to 2 fix attempts per task (default: 1)\nralphctl config set evaluationIterations 0   # Disable evaluation entirely\n```\n\n`sprint start --no-evaluate` skips evaluation for a single run without touching the global setting.\n\n\u003cdetails\u003e\n\u003csummary\u003eProvider differences\u003c/summary\u003e\n\n| Feature                     | Claude Code                          | GitHub Copilot                                                       |\n| --------------------------- | ------------------------------------ | -------------------------------------------------------------------- |\n| Status                      | GA                                   | Public preview                                                       |\n| Headless execution          | `-p --output-format json`            | `-p --output-format json --autopilot --no-ask-user`                  |\n| Session IDs                 | In JSON output (`session_id`)        | In JSON output (`session_id`), `--share` file as fallback            |\n| Session resume (`--resume`) | Full support                         | Full support                                                         |\n| Per-tool permissions        | Settings files + `--permission-mode` | `--allow-all-tools` (all-or-nothing by default)                      |\n| Fine-grained tool control   | `allow`/`deny` in settings files     | `--allow-tool`, `--deny-tool` flags (not yet used)                   |\n| Rate limit detection        | Validated patterns                   | Borrowed from Claude — not yet validated against real Copilot errors |\n\n\u003c/details\u003e\n\n---\n\n## Data Directory\n\nAll data lives in `~/.ralphctl/` by default. Override with:\n\n```bash\nexport RALPHCTL_ROOT=\"/path/to/custom/data-dir\"\n```\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCLI Command Reference\u003c/strong\u003e\u003c/summary\u003e\n\n### Getting Started\n\n| Command                                          | Description                         |\n| ------------------------------------------------ | ----------------------------------- |\n| `ralphctl`                                       | Interactive menu mode (recommended) |\n| `ralphctl doctor`                                | Check environment health            |\n| `ralphctl config set provider \u003cclaude\\|copilot\u003e` | Set AI provider                     |\n| `ralphctl config show`                           | Show current configuration          |\n| `ralphctl completion install`                    | Enable shell tab-completion         |\n\n### Project \u0026 Sprint Setup\n\n| Command                  | Description                      |\n| ------------------------ | -------------------------------- |\n| `ralphctl project add`   | Register a project and its repos |\n| `ralphctl sprint create` | Create a new sprint (draft)      |\n| `ralphctl sprint list`   | List all sprints                 |\n| `ralphctl sprint show`   | Show current sprint details      |\n| `ralphctl sprint switch` | Quick sprint switcher            |\n| `ralphctl ticket add`    | Add a work item to a sprint      |\n\n### AI-Assisted Planning\n\n| Command                        | Description                             |\n| ------------------------------ | --------------------------------------- |\n| `ralphctl sprint refine`       | Clarify requirements with AI (WHAT)     |\n| `ralphctl sprint plan`         | Generate tasks from requirements (HOW)  |\n| `ralphctl sprint ideate`       | Quick single-session refine + plan      |\n| `ralphctl sprint requirements` | Export refined requirements to markdown |\n\n### Execution \u0026 Monitoring\n\n| Command                    | Description                                            |\n| -------------------------- | ------------------------------------------------------ |\n| `ralphctl sprint start`    | Execute tasks with AI (`--branch` for a sprint branch) |\n| `ralphctl sprint health`   | Diagnose blockers and stale tasks                      |\n| `ralphctl sprint insights` | Analyze evaluator results across tasks                 |\n| `ralphctl status`          | Sprint overview with progress bar                      |\n| `ralphctl task list`       | List tasks in the current sprint                       |\n| `ralphctl task next`       | Show the next unblocked task                           |\n| `ralphctl sprint close`    | Close an active sprint (`--create-pr` for PRs)         |\n| `ralphctl sprint delete`   | Delete a sprint permanently                            |\n\nRun `ralphctl \u003ccommand\u003e --help` for details on any command.\n\n\u003c/details\u003e\n\n---\n\n## Documentation\n\n| Resource                                       | Description                                |\n| ---------------------------------------------- | ------------------------------------------ |\n| [Architecture](./.claude/docs/ARCHITECTURE.md) | Data models, file storage, error reference |\n| [Requirements](./.claude/docs/REQUIREMENTS.md) | Acceptance criteria and feature checklist  |\n| [Contributing](./CONTRIBUTING.md)              | Dev setup, code style, PR process          |\n| [Changelog](./CHANGELOG.md)                    | Version history                            |\n\n**Blog posts:** [Building ralphctl](https://lukasgrigis.dev/blog/building-ralphctl) (backstory) | [From task CLI to agent harness](https://lukasgrigis.dev/blog/ralphctl-agent-harness/) (evaluator deep-dive)\n\n**Further reading:** [Harness Engineering for Coding Agent Users](https://martinfowler.com/articles/harness-engineering.html) — Martin Fowler (April 2026) | [Harness Design for Long-Running Application Development](https://www.anthropic.com/engineering/harness-design-long-running-apps) — Anthropic Engineering\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/lukas-grigis/ralphctl.git\ncd ralphctl\npnpm install\npnpm dev --help          # Run CLI in dev mode (tsx, no build needed)\npnpm build               # Compile for npm distribution (tsup)\npnpm typecheck           # Type check\npnpm test                # Run tests\npnpm lint                # Lint\n```\n\n---\n\n## Contributing\n\nContributions are welcome! Please **open an issue first** to discuss what you'd like to change.\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide — dev setup, code style, PR process, and releasing.\n\nThis project follows the [Contributor Covenant](./CODE_OF_CONDUCT.md) code of conduct.\n\n---\n\n## Security\n\nTo report a vulnerability,\nuse [GitHub's private reporting](https://github.com/lukas-grigis/ralphctl/security/advisories/new).\nSee [SECURITY.md](./SECURITY.md) for details.\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukas-grigis%2Fralphctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukas-grigis%2Fralphctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukas-grigis%2Fralphctl/lists"}