{"id":16726194,"url":"https://github.com/deas/dotfiles","last_synced_at":"2026-02-14T19:31:32.035Z","repository":{"id":142206045,"uuid":"237077195","full_name":"deas/dotfiles","owner":"deas","description":"My dotfiles","archived":false,"fork":false,"pushed_at":"2026-02-02T06:44:34.000Z","size":535,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-02T18:35:44.052Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Nushell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deas.png","metadata":{"files":{"readme":"README-ralph.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":"2020-01-29T20:36:55.000Z","updated_at":"2026-02-02T06:44:38.000Z","dependencies_parsed_at":"2023-10-04T20:25:50.759Z","dependency_job_id":"d4337946-8ee7-4486-98cf-19fbe3fd8022","html_url":"https://github.com/deas/dotfiles","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/deas/dotfiles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deas%2Fdotfiles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deas%2Fdotfiles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deas%2Fdotfiles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deas%2Fdotfiles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deas","download_url":"https://codeload.github.com/deas/dotfiles/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deas%2Fdotfiles/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29453395,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T15:52:44.973Z","status":"ssl_error","status_checked_at":"2026-02-14T15:52:11.208Z","response_time":53,"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":[],"created_at":"2024-10-12T22:52:27.704Z","updated_at":"2026-02-14T19:31:32.031Z","avatar_url":"https://github.com/deas.png","language":"Nushell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ralph - Autonomous AI Coding Loop\n\nRalph is a technique for running AI coding agents in a loop. The AI reads a PRD (Product Requirements Document), picks tasks autonomously, implements them one at a time, and commits after each feature. You can run it in human-in-the-loop mode or go fully AFK (away from keyboard) while it works.\n\n## What is Ralph?\n\nRalph automates incremental development by:\n1. Reading a PRD and progress file\n2. Selecting the next uncompleted task\n3. Implementing the task\n4. Running tests and type checks\n5. Committing changes\n6. Updating progress\n7. Repeating until the PRD is complete\n\n## Prerequisites\n\nBefore using Ralph, you need to install:\n\n1. **Claude Code** - Anthropic's CLI for agentic coding\n   - Install via native binary: `curl -fsSL https://claude.ai/install.sh | bash`\n   - Or via npm: `npm i -g @anthropic-ai/claude-code`\n   - Run `claude` to authenticate with your Anthropic account\n\n2. **Docker Desktop 4.50+** - For running Claude Code in isolated sandboxes\n   - Install from: https://docs.docker.com/desktop/install\n   - Run `docker sandbox run claude` to authenticate\n\n## Files in This Directory\n\n- **PRD.md** - Product Requirements Document containing all tasks\n- **progress.txt** - Log of completed tasks (auto-updated by Ralph)\n- **ralph-once.sh** - Human-in-the-loop mode (run one iteration at a time)\n- **afk-ralph.sh** - Autonomous mode (run multiple iterations unattended)\n\n## Getting Started\n\n### 1. Create Your PRD\n\nEdit `PRD.md` to define your project requirements. You can:\n- Write it manually, or\n- Use Claude's plan mode: run `claude` and press `shift-tab`, then ask Claude to save the plan to `PRD.md`\n\nThe PRD can be in any format (markdown checklist, JSON, plain prose). What matters is:\n- The scope is clear\n- Individual tasks can be identified by the agent\n- Tasks are small enough to implement incrementally\n\n### 2. Make Scripts Executable\n\n```bash\nchmod +x ralph-once.sh\nchmod +x afk-ralph.sh\n```\n\n### 3. Start with Human-in-the-Loop\n\nRun Ralph once to see what it does:\n\n```bash\n./ralph-once.sh\n```\n\nThis runs a single iteration. Watch what Claude does, check the commit, review progress.txt, then run it again when ready.\n\nBenefits:\n- Builds intuition for how the loop works\n- Lets you catch issues early\n- Helps you refine your PRD\n\n### 4. Go AFK (Autonomous Mode)\n\nWhen you're comfortable with how Ralph works, run multiple iterations unattended:\n\n```bash\n./afk-ralph.sh 20\n```\n\nThis runs up to 20 iterations or until the PRD is complete. Claude will:\n- Automatically pick tasks\n- Implement them one by one\n- Run tests and type checks\n- Commit changes\n- Update progress\n- Stop when done (outputs `\u003cpromise\u003eCOMPLETE\u003c/promise\u003e`)\n\n## How It Works\n\n### Human-in-the-Loop Mode (`ralph-once.sh`)\n\n- Uses `--permission-mode acceptEdits` to auto-accept file edits\n- References `@PRD.md` and `@progress.txt` for context\n- Runs interactively (you see the chat interface)\n- Enforces \"ONLY DO ONE TASK AT A TIME\" for small commits\n\n### Autonomous Mode (`afk-ralph.sh`)\n\n- Uses `docker sandbox run claude` for isolation\n- Runs in print mode (`-p`) for non-interactive output\n- Captures output to check for completion sigil\n- Exits early if PRD is complete\n- Caps iterations to prevent runaway costs\n\n## Key Script Elements\n\n| Element | Purpose |\n|---------|---------|\n| `--permission-mode acceptEdits` | Auto-accepts file edits so the loop doesn't stall |\n| `@PRD.md` | Points Claude at your requirements doc |\n| `@progress.txt` | Tracks completed work between runs |\n| `ONLY DO ONE TASK` | Forces small, incremental commits |\n| `set -e` | Exit on any error |\n| `$1` (iterations) | Caps the loop to prevent runaway costs |\n| `-p` | Print mode - non-interactive output |\n| `\u003cpromise\u003eCOMPLETE\u003c/promise\u003e` | Completion sigil Claude outputs when done |\n\n## Tips for Success\n\n### Writing Good PRDs\n\n1. **Be specific** - \"Add user authentication with JWT\" is better than \"Add login\"\n2. **Break it down** - Smaller tasks = smaller commits = easier to review\n3. **Prioritize** - Put high-priority items first\n4. **Include testing** - Mention test requirements in the PRD\n5. **Define success** - Be clear about what \"done\" looks like\n\n### Running Ralph\n\n1. **Start small** - Begin with human-in-the-loop mode\n2. **Monitor progress** - Check commits and progress.txt regularly\n3. **Cap iterations** - Start with 5-10 iterations, increase as you gain confidence\n4. **Review commits** - Check what Claude did before merging\n5. **Iterate on the PRD** - Refine based on what works and what doesn't\n\n## Customization Ideas\n\nRalph is just a loop - you can customize it for different workflows:\n\n### Different Task Sources\n- Pull from GitHub Issues instead of local PRD\n- Use Linear API for task management\n- Read from a Jira board\n\n### Different Outputs\n- Create a branch + PR for each task instead of committing to main\n- Post updates to Slack or Discord\n- Generate documentation automatically\n\n### Different Loop Types\n\n| Loop Type | What It Does |\n|-----------|--------------|\n| Test Coverage | Finds uncovered lines, writes tests until coverage hits target |\n| Linting | Fixes lint errors one by one |\n| Duplication | Detects code duplication, refactors into shared utilities |\n| Entropy | Scans for code smells, cleans them up |\n\nAny task that fits \"look at repo, improve something, commit\" works with Ralph.\n\n## Troubleshooting\n\n### \"command not found: claude\"\nAdd Claude to your PATH:\n```bash\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n```\n\n### Docker sandbox authentication\nRun `docker sandbox run claude` to authenticate. Your credentials are stored in a Docker volume.\n\n### Ralph keeps doing the wrong task\n- Refine your PRD to be more specific\n- Update progress.txt to clearly mark completed tasks\n- Reduce task scope (smaller is better)\n\n### Tests keep failing\n- Add \"ensure tests pass\" as a requirement in the PRD\n- Run human-in-the-loop mode to debug\n- Fix the test infrastructure first, then let Ralph continue\n\n## Resources\n\n- [Original Ralph concept by Geoffrey Huntley](https://ghuntley.com/ralph/)\n- [11 Tips for AI Coding with Ralph](https://www.aihero.dev/tips-for-ai-coding-with-ralph-wiggum)\n- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)\n- [Docker Sandboxes Documentation](https://docs.docker.com/ai/sandboxes/)\n\n## License\n\nThese scripts are provided as examples. Adapt them for your own projects as needed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeas%2Fdotfiles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeas%2Fdotfiles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeas%2Fdotfiles/lists"}