{"id":47793861,"url":"https://github.com/francescoalemanno/ralph-cli","last_synced_at":"2026-04-08T10:02:04.930Z","repository":{"id":348064404,"uuid":"1196057344","full_name":"francescoalemanno/ralph-cli","owner":"francescoalemanno","description":"A Ralph loop implementation in rust, covering structured workflow loops, and freestyle looping. Works with Codex, OpenCode, Raijin","archived":false,"fork":false,"pushed_at":"2026-04-03T16:54:36.000Z","size":940,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T18:25:00.974Z","etag":null,"topics":["ai-agents","ai-orchestration","ai-planner","cli","orchestrator","ralph-loop","ralph-wiggum","rust","tui"],"latest_commit_sha":null,"homepage":"https://github.com/francescoalemanno/ralph-cli","language":"Rust","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/francescoalemanno.png","metadata":{"files":{"readme":"README.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":"2026-03-30T10:27:34.000Z","updated_at":"2026-04-03T16:54:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/francescoalemanno/ralph-cli","commit_stats":null,"previous_names":["francescoalemanno/ralph-cli"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/francescoalemanno/ralph-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francescoalemanno%2Fralph-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francescoalemanno%2Fralph-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francescoalemanno%2Fralph-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francescoalemanno%2Fralph-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/francescoalemanno","download_url":"https://codeload.github.com/francescoalemanno/ralph-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francescoalemanno%2Fralph-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31549900,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"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-agents","ai-orchestration","ai-planner","cli","orchestrator","ralph-loop","ralph-wiggum","rust","tui"],"created_at":"2026-04-03T16:01:30.261Z","updated_at":"2026-04-08T10:02:04.924Z","avatar_url":"https://github.com/francescoalemanno.png","language":"Rust","readme":"# Ralph\n\nRalph is a workflow runner for iterative coding-agent loops.\n\nThink of it as the Ralph Wiggum technique packaged into named workflows: study durable project memory, choose one high-leverage action, do the work, record what changed, and either loop again or stop. By default it opens a terminal UI; add `--cli` when you want a scriptable, plain-terminal run.\n\n![Ralph TUI](tui.png)\n\n## Ralph Philosophy\n\n- Iteration beats one-shot prompting. Ralph is for repeated loops that tighten the repository over time, not for hoping one giant prompt gets everything right.\n- One item per loop. The built-in workflows deliberately try to pick one high-leverage item, or send the agent back to planning when the work is still ambiguous.\n- Durable memory beats bloated context. Files such as `PLAN.md`, `progress.txt`, and design docs under `docs/` are the stable memory each loop reloads.\n- Failures are data. A bad search result, broken build, or stale plan is usually a signal to tune the workflow inputs or guardrails.\n- Backpressure matters. Ralph works best when each loop can run the checks that reject placeholders and shallow implementations.\n- Operator skill still matters. Ralph automates the loop, not engineering judgment; you still need to define success clearly and tune the artifacts when the loop drifts.\n\n## When Ralph Works Best\n\n- Well-defined engineering work with observable success criteria\n- Greenfield work or bounded refactors where automated checks can provide fast feedback\n- Repositories where `PLAN.md`, `progress.txt`, or design docs can stay current\n- Long-running or unattended iteration where you want auditable handoffs between loops\n\n## When Ralph Is A Bad Fit\n\n- Tasks whose success is mostly taste, negotiation, or external approval\n- Huge vague requests that actually need design work first\n- Changes that cannot be validated with tests, linters, type checkers, or smoke tests\n- Repositories where nobody will maintain the plan/spec artifacts Ralph depends on\n\n## What Ralph Gives You\n\n- Named, repeatable loops instead of rebuilding the prompt stack every run\n- Built-in workflows that separate planning from building when needed\n- Agent portability across Codex, Claude Code, Gemini CLI, OpenCode, Droid, Pi Coding, and Raijin\n- User defaults and per-project overrides kept separate\n- Editable workflow definitions and auditable run artifacts under `.ralph/`\n\n## Install\n\n### Release Installer\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/francescoalemanno/ralph-cli/main/install | bash\n```\n\nThe installer downloads a release binary for macOS or Linux on `x86_64` and `arm64`, installs `ralph` into `~/.local/bin` by default, and adds that directory to common shell profiles if needed.\n\nUseful installer overrides:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/francescoalemanno/ralph-cli/main/install | \\\n  RALPH_INSTALL_DIR=\"$HOME/bin\" RALPH_VERSION=\"vX.Y.Z\" bash\n```\n\n### From Source\n\n```bash\ncargo install --path crates/ralph-cli\n```\n\nOr build the binary directly:\n\n```bash\ncargo build --release -p ralph-cli\n./target/release/ralph --help\n```\n\n## First Run\n\nStart with:\n\n```bash\nralph doctor\nralph agent list\nralph ls\n```\n\n`ralph doctor` validates config, seeds the built-in workflow registry if missing, ensures `.ralph/` can be created in the current project, and reports which supported agents were detected on `PATH`.\n\n## Choose The Right Workflow\n\n- `bare`: use this when your request already contains the exact loop discipline you want and you just need Ralph to run it durably.\n- `dbv`: use this when you want a durable plan in `PLAN.md`, one-item-at-a-time execution, and a final whole-project verification pass before declaring success.\n- `task-based`: use this when the work already lives in a request list or `progress.txt` and you want one right-sized item completed per loop.\n- `pdd`: use this when the idea is still rough and you need an interactive path to research, design, and an implementation plan before autonomous loops.\n\n## Core Concepts\n\n- Workflow: a YAML definition selected with `ralph run \u003cworkflow-id\u003e ...`\n- Agent: the coding tool Ralph launches underneath the workflow\n- Request: the task text for the workflow\n- Design docs/specs: optional durable reference material when the request needs them\n- Plan file: a prioritized list of right-sized build items, usually `PLAN.md`\n- Progress file: the handoff memory for the next loop, usually `progress.txt`\n- User config: `~/.config/ralph/config.toml`\n- Workflow registry: `~/.config/ralph/workflows/`\n- Project config: `.ralph/config.toml`\n\nEvery command also accepts `--project-dir \u003cPATH\u003e` if you want to operate on a different repository without changing directories.\n\n## Running Workflows\n\n### Default Mode: TUI\n\nThese open the runner UI:\n\n```bash\nralph run task-based \"fix the failing tests\"\nralph run dbv \"ship the auth refactor\"\nralph run pdd --file rough-idea.md\n```\n\nImportant behavior:\n\n- TUI mode requires a workflow and a request.\n- In TUI mode, provide the request either as argv text or with `--file`.\n- Piped stdin is not supported in TUI mode because the terminal is needed for interaction.\n\n### CLI Mode\n\nUse `--cli` for a plain terminal run:\n\n```bash\nralph run --cli bare \"summarize the current repository\"\nralph run --cli task-based --progressfile progress.txt \"finish the top task\"\ncat REQ.md | ralph run --cli bare\n```\n\nCLI mode also accepts piped stdin. For workflows with interactive prompts, do not use stdin; use argv text or `--file` so the terminal stays available.\n\n### Request Input Rules\n\nRalph accepts the workflow request in exactly one runtime form:\n\n- argv text\n- `--file \u003cFILE\u003e`\n- stdin, but only in `--cli` mode\n\nIf you provide more than one, Ralph exits with a usage error.\n\n## Writing Better Ralph Requests\n\n- Define success criteria in observable terms: what should work, what should pass, and what files or docs should be updated.\n- Keep the active loop narrow. If the work is broad or ambiguous, start with `pdd` to design it first or `dbv` to repair the plan before building.\n- Point Ralph at durable memory such as `PLAN.md`, design docs, or `progress.txt`.\n- Tell Ralph to study the code before deciding something is missing. This is one of the most common failure modes in agentic loops.\n- Ask for the relevant checks after each change so the loop has real backpressure.\n- Treat plan and progress files as living control surfaces. If they get stale, rewrite them and keep looping.\n\n## Built-In Workflows\n\n| Workflow | What it does | Useful options |\n| --- | --- | --- |\n| `bare` | Minimal wrapper when your request already contains the loop discipline you want. | None |\n| `dbv` | Uses a durable `PLAN.md` as the control surface, decomposes when needed, builds one item per loop, and performs whole-project verification when the plan is complete. | `--planfile` (default: `PLAN.md`) |\n| `task-based` | Reads the request list, chooses one high-priority right-sized item, executes it, and updates a handoff file for the next loop. | `--progressfile` (default: `progress.txt`) |\n| `pdd` | Interactive prompt-driven development for turning a rough idea into research, design, and an implementation plan. | `--pdddir` (default: `docs/planning/{project_name}`) |\n\nList them at any time with:\n\n```bash\nralph ls\n```\n\n## Tuning The Loop\n\n- If Ralph keeps grabbing work that is too large, shrink the plan items until one loop can finish one item completely.\n- If Ralph duplicates code that already exists, strengthen the instruction to study the codebase first and keep specs aligned with reality.\n- If Ralph compiles but does shallow work, tighten the success criteria and require the checks that would fail on placeholders.\n- If `progress.txt` or `PLAN.md` turns into noise, rewrite it into a shorter prioritized list and continue the loop.\n- Use `--max-iterations` as a safety net when you are testing a workflow or running unattended.\n\n## Common Commands\n\n```bash\nralph --help\nralph run --help\nralph run dbv --help\nralph ls\nralph show dbv\nralph edit dbv\nralph agent list\nralph agent current\nralph agent set claude --scope user\nralph config show --scope effective\nralph config path\nralph init --agent opencode --editor nvim --max-iterations 20\nralph doctor\n```\n\n## Agents And Config\n\nInspect detected agents:\n\n```bash\nralph agent list\n```\n\nShow the effective agent for the current project:\n\n```bash\nralph agent current\n```\n\nPersist a default agent:\n\n```bash\nralph agent set opencode --scope user\nralph agent set claude --scope project\n```\n\nConfig scopes:\n\n- `user`: your global Ralph defaults\n- `project`: overrides for the current repository\n- `effective`: merged view of both\n\nSet `RALPH_CONFIG_HOME` if you want Ralph's user config and workflow registry somewhere other than `~/.config/ralph`.\n\nShow config:\n\n```bash\nralph config show --scope user\nralph config show --scope project\nralph config show --scope effective\n```\n\nCreate a project config file:\n\n```bash\nralph init --agent opencode --editor nvim --max-iterations 20\n```\n\nNotes:\n\n- The default built-in agent is `opencode`.\n- On startup Ralph keeps the configured agent when it is available; otherwise it falls back to the first detected agent in priority order: `opencode`, `raijin`, then the remaining configured agents.\n- The default workflow iteration limit is `40`.\n- `ralph init` writes `.ralph/config.toml`.\n- Re-run `ralph init` with `--force` to overwrite an existing project config.\n\n## Inspecting And Editing Workflows\n\nList workflow definitions and where they live:\n\n```bash\nralph ls\n```\n\nPrint the raw YAML for one workflow:\n\n```bash\nralph show task-based\n```\n\nEdit a workflow in place:\n\n```bash\nralph edit task-based\n```\n\nEditor resolution order:\n\n1. project `editor_override`\n2. `VISUAL`\n3. `EDITOR`\n4. Ralph's built-in terminal editor\n\nIf Ralph falls back to the built-in editor, `Ctrl-S` saves and `Ctrl-Q` closes it.\n\n## Workflow Option Flags\n\nWorkflow option ids are turned into long flags by removing `-` and `_`.\n\nExamples:\n\n- `progress-file` becomes `--progressfile`\n- `plan-file` becomes `--planfile`\n- `pdd-dir` becomes `--pdddir`\n\nThat is why the workflow-specific help output looks slightly different from the YAML option ids.\n\n## Files Ralph Creates\n\n- `~/.config/ralph/config.toml`: user-level config and built-in agent registry\n- `~/.config/ralph/workflows/*.yml`: workflow registry; built-ins are seeded here automatically\n- `.ralph/config.toml`: project-level config\n- `.ralph/runs/\u003cworkflow-id\u003e/\u003crun-id\u003e/request.txt`: saved request text for a run\n- `.ralph/runs/\u003cworkflow-id\u003e/\u003crun-id\u003e/.ralph-runtime/agent-events.wal.ndjson`: loop-control event log\n\nFiles Ralph commonly reads or updates as part of the workflow itself:\n\n- `PLAN.md`: durable execution plan for `dbv`\n- `progress.txt`: task handoff memory for `task-based`\n- `docs/planning/\u003cproject\u003e/design/detailed-design.md`: design output from `pdd`\n- `docs/planning/\u003cproject\u003e/implementation/plan.md`: execution-ready plan output from `pdd`\n\n## Advanced: `ralph emit`\n\n`ralph emit` is mainly for workflow authors and the agent processes Ralph launches. Most users can ignore it.\n\nIt only works inside an active Ralph run and appends events to the current run's WAL. Built-in workflows use it to control looping behavior, for example:\n\n- `loop-continue`\n- `loop-route \u003cprompt-id\u003e`\n- `loop-stop:ok \u003creason\u003e`\n- `loop-stop:error \u003creason\u003e`\n\nSee the built-in workflow definitions with `ralph show \u003cworkflow-id\u003e` if you want to study how loop control works in practice.\n\n## A Good Daily Flow\n\nIf the work is still fuzzy, start with `pdd` and turn the idea into durable docs:\n\n```bash\nralph run pdd --file rough-idea.md\n```\n\nIf the work is implementation-ready but the plan may still need repair before coding, use `dbv`:\n\n```bash\nralph run dbv \"add SSO to the admin app\"\n```\n\nIf you already have a request list and want one-item handoffs, use `task-based` with a maintained `progress.txt`:\n\n```bash\nralph run task-based \"work through the next highest-priority backlog item\"\n```\n\nIf you want plain terminal output instead of the UI, or you are scripting a run:\n\n```bash\nralph run --cli dbv \"add SSO to the admin app\"\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrancescoalemanno%2Fralph-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrancescoalemanno%2Fralph-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrancescoalemanno%2Fralph-cli/lists"}