{"id":46545408,"url":"https://github.com/mfaux/ralphai","last_synced_at":"2026-03-17T14:38:38.054Z","repository":{"id":342037971,"uuid":"1172360550","full_name":"mfaux/ralphai","owner":"mfaux","description":"Autonomous task runner for AI coding agents. Fresh context every turn.","archived":false,"fork":false,"pushed_at":"2026-03-08T19:16:53.000Z","size":549,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-10T10:45:25.699Z","etag":null,"topics":["ai-automation","ai-coding-agent","autonomous-coding","claude-code","cli","developer-tools","opencode","task-runner"],"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/mfaux.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-04T08:12:08.000Z","updated_at":"2026-03-09T11:06:17.000Z","dependencies_parsed_at":"2026-03-10T05:00:38.935Z","dependency_job_id":null,"html_url":"https://github.com/mfaux/ralphai","commit_stats":null,"previous_names":["mfaux/ralphai"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/mfaux/ralphai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfaux%2Fralphai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfaux%2Fralphai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfaux%2Fralphai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfaux%2Fralphai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mfaux","download_url":"https://codeload.github.com/mfaux/ralphai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfaux%2Fralphai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30372532,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T21:41:54.280Z","status":"online","status_checked_at":"2026-03-11T02:00:07.027Z","response_time":84,"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":["ai-automation","ai-coding-agent","autonomous-coding","claude-code","cli","developer-tools","opencode","task-runner"],"created_at":"2026-03-07T02:13:23.667Z","updated_at":"2026-03-17T14:38:38.045Z","avatar_url":"https://github.com/mfaux.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ralphai\n\nPut your AI coding agent on autopilot.\n\nRalphai takes plans (markdown files) from a backlog and drives any CLI-based coding agent to implement them, with branch isolation, feedback loops, and stuck detection built in. You write the plans, or have your agent write them. Ralphai does the rest.\n\nRequires Node.js 18+ (or Bun/Deno) and a [supported CLI agent](#supported-agents).\n\n## Try It Now\n\n```bash\nnpx ralphai init --yes           # scaffold .ralphai/ with a sample plan\nnpx ralphai run                  # watch the agent complete the sample plan\n```\n\n`init --yes` creates a sample plan in the backlog so you can see the full loop immediately, no plan writing required. It auto-detects installed agents, checking **Claude Code** and **OpenCode** first, then other supported agents. Falls back to OpenCode if none are found. Use `--agent-command=\u003ccmd\u003e` to override (e.g. `--agent-command='claude -p'`).\n\n## Why Ralphai?\n\nAI coding agents get worse the longer they run. As the conversation grows, the model drops older context: it forgets what it tried, repeats mistakes, and drifts.\n\nRalphai avoids this by starting each turn with a **fresh session**: just the plan and a progress log. No conversation history to lose. No drift.\n\n- **No context rot** — turn 10 is as sharp as turn 1\n- **Fresh feedback** — real build output every cycle, never recalled from memory\n- **Stuck detection** — stops burning tokens when progress stalls\n\n[How it works →](docs/how-ralphai-works.md)\n\n## Install\n\n```bash\nnpm install -g ralphai       # install globally for regular use\nnpx ralphai                  # run without installing\n```\n\n## Get Started\n\nIn your project repository:\n\n```bash\nralphai init                 # scaffold .ralphai/ and ralphai.json\n```\n\nRalphai detects your package manager and build scripts automatically. Use `--yes` to skip prompts and auto-detect your installed agent.\n\nAll Ralphai files are gitignored by default; your workflow config is personal. To share config with your team instead, use `ralphai init --shared` to track `ralphai.json` in git. See [Workflows](docs/workflows.md) for details.\n\n## Workflow\n\n### 1. Write plans\n\nAsk your coding agent to create plan files in the Ralphai backlog, using `.ralphai/PLANNING.md` as a guide.\n\n```\nCreate a plan in the ralphai backlog for adding dark mode support.\nUse .ralphai/PLANNING.md as a guide.\n```\n\n### 2. Run\n\nRalphai creates a **`ralphai/\u003cplan-slug\u003e`** branch from your base branch by default, so there is no need to create a feature branch yourself.\n\n```bash\nralphai run\n```\n\nEach turn: the agent reads the plan, implements the next task, runs build/test/lint, fixes errors, and commits. Then a fresh session starts for the next turn.\n\n```bash\nralphai run --turns=3    # 3 turns per plan (default: 5)\nralphai run --turns=0    # unlimited turns\nralphai run --pr         # create a ralphai/* branch and open a PR\nralphai run --patch      # leave changes uncommitted (requires feature branch)\nralphai run --continuous # keep processing backlog plans after the first\nralphai run --resume     # auto-commit dirty state and continue\nralphai run --dry-run    # preview without changing anything\n```\n\nFor parallel work, run in a [git worktree](docs/worktrees.md):\n\n```bash\nralphai worktree                    # auto-pick next backlog plan\nralphai worktree list               # show active worktrees\nralphai worktree clean              # remove completed worktrees\n```\n\n### 3. Steer\n\nPlans flow through the pipeline:\n\n```\nparked/    backlog/  →  in-progress/  →  out/\n```\n\nPark unready plans in `parked/`. Ralphai ignores that folder.\nPlans are flat `.md` files in `backlog/` (for example `backlog/my-plan.md`). The runner creates a slug folder automatically when moving a plan to `in-progress/`.\n\n### 4. Pause and resume\n\nStop mid-run any time. Work stays in `in-progress/\u003cslug\u003e/`. Resume with `ralphai run`, which auto-detects in-progress work. Use `--resume` to auto-commit any dirty working tree state before continuing.\n\n```bash\nralphai status           # see what's queued, in progress, and any problems\nralphai doctor           # validate your setup (agent, feedback commands, config)\nralphai reset            # move in-progress plans back to backlog\nralphai purge            # delete archived artifacts from pipeline/out/\n```\n\n### 5. Close the learnings loop\n\nRalphai logs mistakes to `.ralphai/LEARNINGS.md` (gitignored) and flags durable lessons in `.ralphai/LEARNING_CANDIDATES.md` for human review. After a run, review candidates and promote useful ones to `AGENTS.md` or skill docs. [More on learnings -\u003e](docs/how-ralphai-works.md#learnings-system)\n\n## GitHub Issues Integration\n\nRalphai can pull plans from GitHub issues when the backlog is empty. Label issues with `ralphai` (configurable), and Ralphai converts them into plan files, runs them, and comments progress back on the issue.\n\n```bash\nralphai run --issue-source=github              # pull labeled issues\nralphai run --issue-label=ai-task              # custom label filter\n```\n\nRequires the `gh` CLI. Configure via `issueSource`, `issueLabel`, and related keys in `ralphai.json`. See the [CLI Reference](docs/cli-reference.md#issue-tracking) for all options.\n\n## Manage Your Installation\n\n```bash\nralphai update           # update to the latest version\nralphai teardown         # remove Ralphai from your project\n```\n\n## Monorepo Support\n\n`ralphai init` automatically detects workspace packages from `pnpm-workspace.yaml` or the `workspaces` field in `package.json`. In interactive mode, it offers to add per-workspace feedback commands to `ralphai.json`. In `--yes` mode, it prints the detected workspaces and relies on automatic scope filtering at runtime.\n\nPlans can target a specific package by adding `scope` to the frontmatter:\n\n```md\n---\nscope: packages/web\n---\n```\n\nWhen a plan has a scope, Ralphai rewrites feedback commands using the package manager's workspace filter (e.g., `pnpm --filter @org/web build`). The agent prompt includes a hint to focus on the scoped directory.\n\n`ralphai status` annotates each plan with its scope when declared, and `ralphai doctor` validates per-workspace feedback commands when a `workspaces` config exists (failures produce warnings, not hard errors).\n\nFor custom per-package overrides, add a `workspaces` key to `ralphai.json`:\n\n```json\n{\n  \"workspaces\": {\n    \"packages/web\": {\n      \"feedbackCommands\": [\"pnpm --filter web build\", \"pnpm --filter web test\"]\n    }\n  }\n}\n```\n\n## Supported Agents\n\nRalphai works with any CLI agent that accepts a prompt argument. **Claude Code** and **OpenCode** are actively tested.\n\n\u003cdetails\u003e\n\u003csummary\u003eAgent commands\u003c/summary\u003e\n\n| Agent       | Command                          | Status   |\n| ----------- | -------------------------------- | -------- |\n| Claude Code | `claude -p`                      | Tested   |\n| OpenCode    | `opencode run --agent build`     | Tested   |\n| Codex       | `codex exec`                     | Untested |\n| Gemini CLI  | `gemini -p`                      | Untested |\n| Aider       | `aider --message`                | Untested |\n| Goose       | `goose run -t`                   | Untested |\n| Kiro        | `kiro-cli chat --no-interactive` | Untested |\n| Amp         | `amp -x`                         | Untested |\n\n\u003c/details\u003e\n\n## Reference\n\n- [CLI Reference](docs/cli-reference.md) — all commands, flags, and configuration\n- [How Ralphai Works](docs/how-ralphai-works.md) — context rot, feedback loops, stuck detection\n- [Worktrees](docs/worktrees.md) — parallel runs in isolated directories\n- [Workflows](docs/workflows.md) — common patterns and recipes\n- [Troubleshooting](docs/troubleshooting.md) — common issues and fixes\n\n## Acknowledgements\n\n- [Ralph](https://ghuntley.com/ralph/) by Geoffrey Huntley — creator of the technique behind the loop\n- [Getting Started With Ralph](https://www.aihero.dev/getting-started-with-ralph) by Matt Pocock\n- [Vercel CLI](https://github.com/vercel/vercel) for CLI DX inspiration\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfaux%2Fralphai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmfaux%2Fralphai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfaux%2Fralphai/lists"}