{"id":40272855,"url":"https://github.com/nitodeco/ralph","last_synced_at":"2026-01-24T20:51:26.408Z","repository":{"id":333559384,"uuid":"1137762845","full_name":"nitodeco/ralph","owner":"nitodeco","description":"Ralph is a CLI to orchetrate coding agents.","archived":false,"fork":false,"pushed_at":"2026-01-20T03:48:55.000Z","size":305,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-20T08:20:52.857Z","etag":null,"topics":["agents","claude-code","cli","cursor-ai"],"latest_commit_sha":null,"homepage":"","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/nitodeco.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-19T19:58:56.000Z","updated_at":"2026-01-20T03:48:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nitodeco/ralph","commit_stats":null,"previous_names":["nitodeco/ralph"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/nitodeco/ralph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitodeco%2Fralph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitodeco%2Fralph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitodeco%2Fralph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitodeco%2Fralph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nitodeco","download_url":"https://codeload.github.com/nitodeco/ralph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitodeco%2Fralph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28736767,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T19:23:36.361Z","status":"ssl_error","status_checked_at":"2026-01-24T19:23:28.966Z","response_time":89,"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":["agents","claude-code","cli","cursor-ai"],"created_at":"2026-01-20T03:00:25.886Z","updated_at":"2026-01-24T20:51:26.403Z","avatar_url":"https://github.com/nitodeco.png","language":"TypeScript","funding_links":[],"categories":["Implementations"],"sub_categories":["Standalone Implementations"],"readme":"# Ralph\n\n\u003cdiv align=\"center\"\u003e\n\n## A CLI tool for long-running PRD-driven development with AI coding agents\n\n[![Version](https://img.shields.io/github/v/release/nitodeco/ralph)](https://github.com/nitodeco/ralph/releases/latest)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\n![Ralph Screenshot](docs/image.png)\n\n\u003c/div\u003e\n\nRalph automates the process of working through a Product Requirements Document (PRD) by orchestrating AI coding agents (Cursor, Claude Code, or Codex) to complete tasks one at a time.\n\n## Installation\n\nInstall Ralph with a single command:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/nitodeco/ralph/main/scripts/install.sh | bash\n```\n\n## Quick Start\n\n### 1. Initialize a new project\n\n```bash\nralph init\n```\n\nThis will interactively create all necessary files in the user directory (`~/.ralph`). You'll be prompted to select your preferred AI agent (Cursor, Claude Code, or Codex).\n\n### 2. Run the agent\n\n```bash\nralph run [iterations]\n```\n\nRuns the configured AI agent in a loop, working through tasks in your PRD. Default is 10 iterations.\n\n**The agent workflow:**\n\n1. Run `ralph progress` and `ralph task list` to understand the current state\n2. Run `ralph task current` to find the next incomplete task\n3. Implement that task\n4. Run `ralph progress add` and `ralph task done` to record progress\n5. Commit the changes\n6. Repeat until all tasks are complete or iterations are exhausted\n\n## PRD Format\n\nRalph uses JSON under the hood to store the PRD and progress. The PRD can be easily edited using commands in ralph.\n\n## Configuration\n\n### Custom Instructions\n\nYou can provide project-specific instructions to the agent by creating an `instructions.md` file in your project's Ralph directory (`~/.ralph/projects/\u003cproject\u003e/instructions.md`). The contents of this file will be included in the agent prompt, allowing you to customize behavior, coding standards, or project-specific guidelines.\n\n### Configuration Options\n\nRalph uses a layered configuration system with global (`~/.ralph/config.json`) and project-level (`~/.ralph/projects/\u003cproject\u003e/config.json`) settings. Project settings override global settings.\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `agent` | `\"cursor\"` \\| `\"claude\"` \\| `\"codex\"` | `\"cursor\"` | AI coding agent to use |\n| `maxRetries` | number | `3` | Maximum retry attempts per iteration |\n| `retryDelayMs` | number | `5000` | Delay between retries (ms) |\n| `agentTimeoutMs` | number | `1800000` | Agent timeout per iteration (30 min) |\n| `stuckThresholdMs` | number | `300000` | Time without output before considering agent stuck (5 min) |\n| `maxRuntimeMs` | number | `0` | Maximum total session runtime (0 = unlimited) |\n| `logFilePath` | string | `\".ralph/ralph.log\"` | Path to log file |\n\n#### Notification Settings\n\n```json\n{\n  \"notifications\": {\n    \"systemNotification\": true,\n    \"webhookUrl\": \"https://hooks.slack.com/...\",\n    \"markerFilePath\": \".ralph/complete.marker\"\n  }\n}\n```\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `systemNotification` | boolean | Enable OS notifications on completion |\n| `webhookUrl` | string | Webhook URL for completion notifications |\n| `markerFilePath` | string | File to create when session completes |\n\n#### Memory Settings\n\n```json\n{\n  \"memory\": {\n    \"maxOutputBufferBytes\": 5242880,\n    \"memoryWarningThresholdMb\": 500,\n    \"enableGarbageCollectionHints\": true\n  }\n}\n```\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `maxOutputBufferBytes` | number | `5242880` | Max agent output buffer size (5 MB) |\n| `memoryWarningThresholdMb` | number | `500` | Memory warning threshold |\n| `enableGarbageCollectionHints` | boolean | `true` | Enable GC hints for memory management |\n\n### Example Configuration\n\n```json\n{\n  \"agent\": \"claude\",\n  \"maxRetries\": 5,\n  \"retryDelayMs\": 10000,\n  \"agentTimeoutMs\": 3600000,\n  \"stuckThresholdMs\": 600000,\n  \"maxRuntimeMs\": 28800000,\n  \"notifications\": {\n    \"systemNotification\": true,\n    \"webhookUrl\": \"https://hooks.slack.com/services/...\"\n  }\n}\n```\n\n## Requirements\n\nOne of the following AI coding agents must be installed and available in your PATH:\n\n- **[Cursor CLI](https://docs.cursor.com/cli)** - available as `agent` command\n- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** - available as `claude` command\n- **[Codex CLI](https://github.com/openai/codex)** - available as `codex` command\n\n## Development\n\nContributions are welcome! To get started with development:\n\n```bash\n# Install dependencies\nbun install\n\n# Run in development mode\nbun run dev\n\n# Build binaries\nbun run build\n\n# Type check\nbun run typecheck\n```\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitodeco%2Fralph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnitodeco%2Fralph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitodeco%2Fralph/lists"}