{"id":50748677,"url":"https://github.com/giocaizzi/ralph-copilot","last_synced_at":"2026-06-10T23:03:05.110Z","repository":{"id":340852289,"uuid":"1145912249","full_name":"giocaizzi/ralph-copilot","owner":"giocaizzi","description":"Copilot implementation of Ralph loop","archived":false,"fork":false,"pushed_at":"2026-05-18T11:16:33.000Z","size":1708,"stargazers_count":130,"open_issues_count":0,"forks_count":13,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-05-18T12:33:26.604Z","etag":null,"topics":["agent","copilot","ralph","ralph-loop","ralph-wiggum","vscode"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/giocaizzi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-30T11:25:36.000Z","updated_at":"2026-05-14T20:58:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/giocaizzi/ralph-copilot","commit_stats":null,"previous_names":["giocaizzi/vscode-ralph"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/giocaizzi/ralph-copilot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giocaizzi%2Fralph-copilot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giocaizzi%2Fralph-copilot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giocaizzi%2Fralph-copilot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giocaizzi%2Fralph-copilot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giocaizzi","download_url":"https://codeload.github.com/giocaizzi/ralph-copilot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giocaizzi%2Fralph-copilot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34174148,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"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","copilot","ralph","ralph-loop","ralph-wiggum","vscode"],"created_at":"2026-06-10T23:03:01.272Z","updated_at":"2026-06-10T23:03:05.104Z","avatar_url":"https://github.com/giocaizzi.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Copilot Ralph Loop\n\nA lightweight Copilot implementation of the autonomous agent loop [**Ralph Wiggum as a \"software engineer\"** pattern by Geoffrey Huntley](https://ghuntley.com/ralph/), using custom agents with automatic handoffs.\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/ralph-copilot.png\" height=\"200\" alt=\"Ralph Copilot\"\u003e\u003c/p\u003e\n\nBased on only four `agent.md` markdown files, this pattern enables an **autonomous coding loop** with **fresh context every iteration**, using the filesystem as memory and `git` for version control.\n\n## What is Ralph Loop?\n\n**Ralph loop = Fresh context + Filesystem memory \u0026 Git versioning**\n\nAn autonomous coding pattern where:\n\n0. User provides requirements to a `RalphPlanner` agent, which creates a `PRD.md` with a list of specific tasks and a file to track progress `PROGRESS.md`\n1. User reviews `PRD.md` and starts the loop with `RalphCoordinator` agent who dispatches tasks to `RalphExecutor` agents.\n2. `RalphExecutor` agent picks a task from `PRD.md`\n3. Executes it with **fresh context**, code is tested and quality checks ensured\n4. `git` commits and updates `PROGRESS.md`\n5. Code is reviewed by `RalphReviewer`\n6. Loops until all tasks complete\n\n### Execution Flow\n\n```mermaid\nsequenceDiagram\n    participant H as 👤 User\n    participant P as 🤖 Planner\n    participant C as 🤖 Coordinator\n    participant E as 🤖 Executor\n    participant R as 🤖 Reviewer\n    participant FS as 📝 Filesystem\n\n    H-\u003e\u003eP: Requirements\n    P-\u003e\u003eFS: Write PRD.md + PROGRESS.md\n    P--\u003e\u003eH: Handoff button: Start Ralph Loop\n\n    H-\u003e\u003eC: Start loop\n\n    loop Until all tasks complete\n        C-\u003e\u003eFS: Read PRD.md + PROGRESS.md\n        C-\u003e\u003e+E: Spawn subagent (task + criteria)\n        E-\u003e\u003eFS: Read PRD.md + PROGRESS.md\n        E-\u003e\u003eE: Implement task\n        E-\u003e\u003e+R: Spawn subagent (verify task)\n        R-\u003e\u003eFS: Read code + acceptance criteria\n        R--\u003e\u003e-E: Verdict (pass / fail + notes)\n        E-\u003e\u003eFS: Update PROGRESS.md\n        E-\u003e\u003eFS: git commit\n        E--\u003e\u003e-C: Completion summary\n    end\n\n    C--\u003e\u003eH: COMPLETE\n```\n\n## Features\n\n- 🤝 **Automatic handoffs** - Agents pass control automatically with fresh context\n- 📝 **Progress file and filesystem memory** - Fresh context every iteration via `PROGRESS.md` and `git`\n- 🌐 **Language agnostic** - Works with any programming language/stack\n- ⚛️ **Atomic tasks** - One task per iteration, committed immediately\n- 🔄 **Context reset** - Avoids context pollution, uses filesystem as memory\n- 🔍 **Built-in review** - Reviewer subagent verifies every task before moving on\n- ✅ **Code that lasts** - Maintainable code with tests and quality checks at every iteration\n\n## Compatibility\n\n- 🖥️ **VS Code Copilot** - save agents in the workspace `.github/agents` or [customize your settings.json](#Installation)\n- 🤖 **Copilot CLI** - save agents in workspace `.github/agents` or in global `~/.copilot/agents`\n\n## Setup\n\n### Installation\n\n1. Clone repository and copy agent files to your project:\n\n```bash\ngit clone git@github.com:giocaizzi/ralph-copilot.git\ncp ralph-copilot/agents/*.agent.md \u003cyour_project\u003e/.github/agents/\n```\n\n2. Restart VSCode/Copilot CLI\n\n3. Verify agents are available:\n   - Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)\n   - Type \"Select Agent\"\n   - Should see: `RalphPlanner`, `RalphCoordinator`\n\n\u003e 💡 **Tip — use Ralph globally across all your projects**\n\u003e\n\u003e *VSCode*:\n\u003e Instead of copying agent files per project, point VS Code to your local clone of this repo once via\n\u003e [![VS Code setting chat.agentFilesLocations](https://img.shields.io/badge/VS%20Code-chat.agentFilesLocations-007ACC?style=flat\u0026logo=visualstudiocode\u0026logoColor=white)](vscode://settings/chat.agentFilesLocations)\n\u003e and the agents will be available everywhere.\n\u003e\n\u003e ```jsonc\n\u003e // settings.json\n\u003e \"chat.agentFilesLocations\": {\n\u003e     \"/your/path/to/ralph-copilot\": true\n\u003e }\n\u003e ```\n\u003e\n\u003e *Copilot CLI*\n\u003e Save your agents in the global folder `~/.copilot/agents`\n\n## Usage\n\n### Quick Start\n\n1. **Create PRD** with `RalphPlanner` agent:\n\n   ```\n   Open VSCode Chat\n   Select: RalphPlanner\n   Prompt: \"Create a PRD for [your feature]\"\n   ```\n\n2. **Review PRD.md** - Edit as needed\n\n3. **Start Loop** with `RalphCoordinator` agent:\n\n   ```\n   Select: RalphCoordinator\n   Click: \"Start Ralph Loop\" handoff button\n   ```\n\n4. **Let it run** - Agents will:\n   - Pick tasks from PRD.md\n   - Execute them\n   - Update PROGRESS.md\n   - Commit changes\n   - Review, test and run quality checks\n   - Repeat until done\n\n5. **Monitor progress** in PROGRESS.md and git history\n\n## Credits\n\nBased on:\n\n- [**Ralph Wiggum as a \"software engineer\"** pattern by Geoffrey Huntley](https://ghuntley.com/ralph/)\n- [Ralph](https://github.com/snarktank/ralph)\n- [VSCode Custom Agents Docs](https://code.visualstudio.com/docs/copilot/customization/custom-agents)\n- [Claude Code Ralph Loop](https://github.com/anthropics/claude-code/blob/main/plugins/ralph-wiggum/README.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiocaizzi%2Fralph-copilot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiocaizzi%2Fralph-copilot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiocaizzi%2Fralph-copilot/lists"}