{"id":41790639,"url":"https://github.com/rpothin/ghc-ralph-cli","last_synced_at":"2026-01-28T18:07:56.347Z","repository":{"id":334316847,"uuid":"1140958362","full_name":"rpothin/ghc-ralph-cli","owner":"rpothin","description":"🤖 A GitHub Copilot-powered CLI for running autonomous agentic coding loops using the Ralph Wiggum pattern","archived":false,"fork":false,"pushed_at":"2026-01-25T03:38:14.000Z","size":310,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-25T17:11:23.981Z","etag":null,"topics":["cli","copilot-sdk","github-copilot","ralph-wiggum"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/ghcralph","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/rpothin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-01-24T01:52:01.000Z","updated_at":"2026-01-25T03:38:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rpothin/ghc-ralph-cli","commit_stats":null,"previous_names":["rpothin/ghc-ralph-cli"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/rpothin/ghc-ralph-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpothin%2Fghc-ralph-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpothin%2Fghc-ralph-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpothin%2Fghc-ralph-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpothin%2Fghc-ralph-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rpothin","download_url":"https://codeload.github.com/rpothin/ghc-ralph-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpothin%2Fghc-ralph-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28848434,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T15:15:36.453Z","status":"ssl_error","status_checked_at":"2026-01-28T15:15:13.020Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cli","copilot-sdk","github-copilot","ralph-wiggum"],"created_at":"2026-01-25T05:01:43.033Z","updated_at":"2026-01-28T18:07:56.316Z","avatar_url":"https://github.com/rpothin.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Copilot Ralph CLI (`ghcralph`)\n\n[![CI](https://github.com/rpothin/ghc-ralph-cli/actions/workflows/ci.yml/badge.svg?branch=main\u0026event=push)](https://github.com/rpothin/ghc-ralph-cli/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/ghcralph.svg)](https://www.npmjs.com/package/ghcralph)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)\n\nRun **autonomous, checkpointed coding loops** with GitHub Copilot—designed to be **safe, reversible, and budget-controlled**.\n\n## What you get\n\n- 🌿 **Branch isolation**: works on a `ghcralph/*` branch (never modifies `main`/`master` directly)\n- 💾 **Automatic checkpoints**: commits after each iteration for easy rollback\n- 🛡️ **Guardrails**: iteration limits, token budgets, timeouts, circuit breaker on repeated failures\n- 📋 **Flexible plan sources**: GitHub Issues or local Markdown task lists\n- 💻 **Cross-platform**: Windows, macOS, Linux\n\n## 60-second quick start\n\n### Prerequisites (required)\n- **Node.js** \u003e= 18\n- **git**\n- **GitHub CLI (`gh`)** authenticated\n- **GitHub Copilot CLI extension**:\n  ```bash\n  gh extension install github/gh-copilot\n  ```\n- An active **GitHub Copilot** subscription / access\n\n### Install\n```bash\nnpm install -g ghcralph\n```\n\n### Initialize in your project\n```bash\ncd your-project\nghcralph init\n```\n\n### Run your first task\n```bash\nghcralph run --task \"Add a README badge showing the build status\"\n```\n\n### Rollback if needed\n```bash\nghcralph rollback --iterations 1\n```\n\n## Safety model (read this first)\n\n- **No direct main changes**: the tool creates an isolated branch and works there.\n- **Reversible by design**: each iteration is checkpointed in git; rollback is a first-class command.\n- **Deletion protection**: existing files are protected from deletion by default (override only if you explicitly allow it).\n- **Budgets and limits**: iteration/token/time limits prevent runaway sessions.\n\n---\n\n## What is GitHub Copilot Ralph?\n\nGitHub Copilot Ralph implements the **Ralph Wiggum agentic coding pattern**—a simple, safe, and well-documented approach to running autonomous AI coding loops powered by GitHub Copilot.\n\n### The Ralph Wiggum Pattern\n\nNamed after the delightfully simple character, the pattern is straightforward:\n\n```\n1. Give the agent a task\n2. Let it work in small, checkpointed iterations\n3. Review progress and rollback if needed\n4. Repeat until done\n```\n\nThis approach prioritizes **safety** (automatic checkpoints, git isolation) and **control** (iteration limits, easy rollback) over speed.\n\n## Key Features\n\n- 🔄 **Autonomous Loop**: Repeatedly invokes AI agent until task completion\n- 📋 **Flexible Plan Sources**: GitHub Issues or local Markdown task lists\n- 🛡️ **Safety First**: Git branch isolation, file deletion safeguards\n- 💾 **Automatic Checkpoints**: Git commits after each iteration for easy rollback\n- 📊 **Progress Tracking**: Real-time status, token usage, and session logs\n- ⚡ **Guardrails**: Iteration limits, token budgets, timeout controls\n- 🔧 **Highly Configurable**: Customize behavior via CLI, env vars, or config files\n- 💻 **Cross-Platform**: Works on Windows, macOS, and Linux\n\n## Commands\n\n| Command             | Description                                     |\n| ------------------- | ----------------------------------------------- |\n| `ghcralph init`     | Initialize GitHub Copilot Ralph in a repository |\n| `ghcralph run`      | Execute an agentic coding loop                  |\n| `ghcralph status`   | Check current session status                    |\n| `ghcralph rollback` | Revert to a previous checkpoint                 |\n| `ghcralph config`   | View or modify configuration                    |\n| `ghcralph help`     | Get help for any command                        |\n\nUse `ghcralph \u003ccommand\u003e --help` for detailed options.\n\n## Common workflows\n\n### One-off task (fastest)\n```bash\nghcralph run --task \"Refactor auth middleware to reduce duplication\"\n```\n\n### Run from a local Markdown plan\n```bash\nghcralph run --plan TODO.md\n```\n\n### Run tasks from GitHub Issues\n```bash\nghcralph init --github\nghcralph run --github owner/repo --label \"ready\"\n```\n\n## Usage\n\n### Initialize a Project\n\n```bash\n# Default initialization (local plan source)\nghcralph init\n\n# Use GitHub Issues as plan source\nghcralph init --github\n\n# Use local Markdown files as plan source\nghcralph init --local\n\n# Reinitialize existing configuration\nghcralph init --force\n```\n\n### Run Tasks\n\n```bash\n# Inline task\nghcralph run --task \"Add input validation to the login form\"\n\n# Task from file\nghcralph run --file tasks/add-validation.md\n\n# Tasks from a Markdown plan file\nghcralph run --plan TODO.md\n\n# Tasks from GitHub Issues\nghcralph run --github owner/repo --label \"ready\"\n```\n\n### Advanced Run Options\n\n```bash\n# Control iterations and tokens\nghcralph run --task \"Refactor auth\" --max-iterations 20 --max-tokens 50000\n\n# Specify context files\nghcralph run --task \"Fix tests\" --context \"src/**/*.test.ts\"\n\n# Use a specific branch\nghcralph run --task \"Add feature\" --branch feature/my-feature\n\n# Preview without executing\nghcralph run --task \"Big change\" --dry-run\n\n# Long-running task with timeout\nghcralph run --task \"Large refactor\" --unlimited --timeout 60\n\n# Skip confirmation prompts\nghcralph run --task \"Quick fix\" --force\n```\n\n## Configuration\n\nGitHub Copilot Ralph uses a hierarchical configuration system:\n\n1. **CLI flags** (highest priority)\n2. **Environment variables** (`GHCRALPH_*`)\n3. **Local config** (`.ghcralph/config.json`)\n4. **Global config** (`~/.config/ghcralph/config.json`)\n\n### Configuration Options\n\n| Option          | Default     | Description                                           |\n| --------------- | ----------- | ----------------------------------------------------- |\n| `planSource`    | `local`     | Plan source: `github` or `local`                      |\n| `maxIterations` | `10`        | Maximum loop iterations                               |\n| `maxTokens`     | `100000`    | Token budget                                          |\n| `defaultModel`  | `gpt-4.1`   | Copilot model to use                                  |\n| `autoCommit`    | `true`      | Auto-commit after iterations                          |\n| `branchPrefix`  | `ghcralph/` | Prefix for GitHub Copilot Ralph branches              |\n| `githubRepo`    | -           | GitHub repository (owner/repo) for GitHub plan source |\n| `localPlanFile` | -           | Path to local plan file                               |\n\n### Environment Variables\n\nAll configuration options can be set via environment variables with the `GHCRALPH_` prefix:\n\n```bash\nexport GHCRALPH_MAX_ITERATIONS=20\nexport GHCRALPH_MAX_TOKENS=50000\nexport GHCRALPH_DEFAULT_MODEL=gpt-4.1\nexport GHCRALPH_AUTO_COMMIT=true\nexport GHCRALPH_BRANCH_PREFIX=ghcralph/\nexport GHCRALPH_PLAN_SOURCE=local\n```\n\n### Example Configuration File\n\n```json\n{\n  \"planSource\": \"github\",\n  \"maxIterations\": 15,\n  \"maxTokens\": 50000,\n  \"defaultModel\": \"gpt-4.1\",\n  \"autoCommit\": true,\n  \"branchPrefix\": \"ghcralph/\",\n  \"githubRepo\": \"owner/repo\"\n}\n```\n\n## Safety Features (details)\n\n### 🌿 Git Branch Isolation\n- Automatically creates `ghcralph/` prefixed branches\n- Never modifies `main` or `master` directly\n- Easy to discard unsuccessful attempts\n\n### 💾 Automatic Checkpoints\n- Commits after each successful iteration\n- Message format: `ghcralph: iteration N - summary`\n- Easy rollback with `ghcralph rollback`\n\n### 🛡️ File Deletion Safeguards\n- Tracks files that existed before session\n- Blocks deletion of pre-existing files\n- Override with `--allow-delete` if needed\n\n### ⏱️ Resource Limits\n- Configurable iteration limits\n- Token budget controls\n- Optional timeout (`--timeout`)\n- Requires `--unlimited` flag for \u003e50 iterations\n\n### 🔌 Circuit Breaker\n- Pauses after 3 consecutive failures\n- Warns at 80% of resource limits\n- Graceful shutdown on Ctrl+C\n\n## Authentication\n\nGitHub Copilot Ralph uses GitHub for AI access:\n\n1. **GitHub CLI** (recommended): `gh auth login`\n2. **GitHub Copilot CLI**: Ensure it's installed: `gh extension install github/gh-copilot`\n3. **Environment variable** (alternative): `GITHUB_TOKEN` or `GH_TOKEN`\n\n## Installation\n\n### npm (Recommended)\n\n```bash\nnpm install -g ghcralph\n```\n\n### From source\n\n```bash\ngit clone https://github.com/rpothin/ghc-ralph-cli.git\ncd ghc-ralph-cli\nnpm install\nnpm run build\nnpm link\n```\n\n## Troubleshooting\n\n### \"Not in a git repository\"\nRun `git init` first, or navigate to an existing git repository.\n\n### \"Failed to initialize Copilot agent\"\nEnsure you have GitHub Copilot CLI installed and are authenticated:\n```bash\ngh extension install github/gh-copilot\ngh auth login\n```\n\n### \"Maximum iterations reached\"\nIncrease the limit: `--max-iterations 20`  \nOr for very long tasks: `--unlimited`\n\n### Progress seems stuck\nCheck status: `ghcralph status`  \nView checkpoints: `ghcralph rollback --list`  \nRollback if needed: `ghcralph rollback`\n\n## Credits \u0026 Attribution\n\n**GitHub Copilot Ralph** is an opinionated interpretation of the **Ralph Wiggum loop** approach, originally proposed by **[Geoffrey Huntley](https://ghuntley.com/)**.\n\nThis CLI implementation was created by **[Raphael Pothin](https://github.com/rpothin)** to make the Ralph Wiggum approach:\n\n- 📐 **More structured** - with clear phases and checkpoints\n- 🛡️ **Safer** - with git isolation, file safeguards, and resource limits\n- 🎯 **More accessible** - for developers new to agentic coding patterns\n- 🏢 **Enterprise-ready** - with configuration, audit trails, and controls\n- 🔗 **GitHub ecosystem integrated** - leveraging GitHub Copilot SDK and optionally GitHub Issues\n\n## Philosophy\n\nGitHub Copilot Ralph is built on these principles:\n\n1. **Simplicity first**: Mirror the elegant simplicity of Geoffrey Huntley's original Ralph loop\n2. **Safety by design**: Git isolation, automatic checkpoints, cost controls\n3. **Human-friendly**: Markdown progress, clear documentation, easy rollback\n4. **Cross-platform**: Works seamlessly on Windows, macOS, and Linux\n5. **Transparent**: You can always see what GitHub Copilot Ralph is doing and undo it\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT © [Raphael Pothin](https://github.com/rpothin)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frpothin%2Fghc-ralph-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frpothin%2Fghc-ralph-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frpothin%2Fghc-ralph-cli/lists"}