{"id":39987665,"url":"https://github.com/rem4ik4ever/ralph","last_synced_at":"2026-01-19T00:01:23.016Z","repository":{"id":333324264,"uuid":"1133649892","full_name":"rem4ik4ever/ralph","owner":"rem4ik4ever","description":"PRD-based task tracking CLI for AI coding agents. Run agents headlessly with structured task tracking and progress visibility.","archived":false,"fork":false,"pushed_at":"2026-01-18T22:36:15.000Z","size":238,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-18T23:57:51.002Z","etag":null,"topics":["ai","ai-agent","ai-agents","ai-development","ai-development-tools","claude-code","claude-code-cli","development-tools","development-workflow","ralph-wiggum"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/rem4ik4ever.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-13T16:27:32.000Z","updated_at":"2026-01-18T22:06:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rem4ik4ever/ralph","commit_stats":null,"previous_names":["rem4ik4ever/ralph"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/rem4ik4ever/ralph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rem4ik4ever%2Fralph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rem4ik4ever%2Fralph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rem4ik4ever%2Fralph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rem4ik4ever%2Fralph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rem4ik4ever","download_url":"https://codeload.github.com/rem4ik4ever/ralph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rem4ik4ever%2Fralph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28554368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T23:48:35.235Z","status":"ssl_error","status_checked_at":"2026-01-18T23:47:49.178Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["ai","ai-agent","ai-agents","ai-development","ai-development-tools","claude-code","claude-code-cli","development-tools","development-workflow","ralph-wiggum"],"created_at":"2026-01-19T00:01:22.002Z","updated_at":"2026-01-19T00:01:22.994Z","avatar_url":"https://github.com/rem4ik4ever.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ralph\n\nPRD-based task tracking CLI for AI coding agents. Run agents headlessly with structured task tracking and progress visibility.\n\nInspired by [Geoff Huntley's ralph technique](https://ghuntley.com/ralph/) - putting a coding agent in a while loop and letting it work autonomously.\n\n## Installation\n\n```bash\n# npm\nnpm install -g rlph-cli\n\n# or run directly\nnpx rlph-cli prd add my-feature.md my-feature\n```\n\n### From source\n\n```bash\ngit clone https://github.com/rem4ik4ever/ralph.git\ncd ralph\nbun install\nbun run build\nbun link\n```\n\n## Usage\n\n### Add a PRD\n\nConvert markdown PRD to trackable JSON tasks:\n\n```bash\nralph prd add \u003cpath\u003e \u003cname\u003e [--agent claude]\n```\n\nExample:\n```bash\nralph prd add feature.md my-feature\n```\n\nCreates `~/.ralph/prd/my-feature/` with:\n- `prd.md` - original markdown\n- `prd.json` - converted tasks with pass/fail tracking\n- `progress.txt` - cross-iteration memory\n\n### List PRDs\n\nView all PRDs with status:\n\n```bash\nralph prd list\n```\n\nOutput:\n```\n1. my-feature - Add login flow - in_progress (3/7)\n2. refactor-api - API cleanup - pending (0/4)\n```\n\n### Run PRD\n\nExecute agent loop against a PRD:\n\n```bash\nralph run \u003cprd-name\u003e [--agent claude] [--iterations 4]\n```\n\nExample:\n```bash\nralph run my-feature -i 10\n```\n\nAgent picks up next incomplete task, implements it, runs feedback loops (tests/lint/types), marks task passed, repeats until done.\n\n## How it works\n\n1. Write markdown PRD with tasks and verification steps\n2. `ralph prd add` converts to JSON with agent\n3. `ralph run` loops agent against PRD tasks\n4. Agent updates `prd.json` passes field on completion\n5. Agent maintains `progress.txt` with learnings across iterations\n6. Stops when all tasks pass or max iterations reached\n7. Logs each iteration to `~/.ralph/prd/\u003cname\u003e/iterations/`\n\n## PRD folder structure\n\n```\n~/.ralph/prd/\u003cname\u003e/\n├── prd.md        # Original markdown\n├── prd.json      # Tasks with passes field\n├── progress.txt  # Cross-iteration memory\n└── iterations/   # Iteration logs\n    ├── 0.json\n    └── ...\n```\n\n## Supported agents\n\n- `claude` - Claude Code CLI (requires [claude](https://claude.ai/claude-code) installed)\n\n## Requirements\n\n- Node.js \u003e= 18\n- Claude Code CLI installed and authenticated\n\n## Releases\n\nThis project uses [semantic-release](https://github.com/semantic-release/semantic-release) for automated versioning and npm publishing.\n\n### How it works\n\n1. Push/merge to `main` triggers release workflow\n2. Commits are analyzed to determine version bump\n3. CHANGELOG.md is updated automatically\n4. Package is published to npm\n5. GitHub release is created\n\n### Conventional Commits\n\nCommit messages must follow [Conventional Commits](https://www.conventionalcommits.org/):\n\n```\n\u003ctype\u003e(\u003cscope\u003e): \u003cdescription\u003e\n\n[optional body]\n\n[optional footer]\n```\n\n| Type | Version Bump | Example |\n|------|--------------|---------|\n| `fix` | Patch (1.0.x) | `fix(cli): handle empty input` |\n| `feat` | Minor (1.x.0) | `feat(prd): add export command` |\n| `feat!` or `BREAKING CHANGE:` | Major (x.0.0) | `feat!: change config format` |\n\nOther types (`docs`, `chore`, `refactor`, `test`, `ci`) don't trigger releases.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frem4ik4ever%2Fralph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frem4ik4ever%2Fralph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frem4ik4ever%2Fralph/lists"}