A bounded Ralph loop for coding tasks. Give it a goal; it runs Pi in fresh iterations, carries progress forward, checks the result, and stops when the task is done or a limit is reached.
Requires Node.js 24. Install Pi and the v0.2.0 release, then configure a model in Pi with /login and /model. RalphWorks uses Pi's existing model and credentials; select another configured model with --model provider/model-id.
npm install -g @earendil-works/pi-coding-agent \
https://github.com/OctopusGarage/ralphworks/releases/download/v0.2.0/ralphworks-0.2.0.tgz
pi # configure /login and /model, then exit
cd /path/to/your/repo
ralphworks run 'Fix the login error and add a regression test' --check 'npm test'Run the command from the repository you want to change. Edits stay in that worktree. --check runs after every iteration; a failing check sends its output into the next iteration. Omit it for exploratory work, but use checks that cover the acceptance criteria for unattended tasks.
Without checks, completed means the agent reported completion; it does not independently verify the result.
- Pi reads the task and saved progress, then works on one useful increment.
- RalphWorks runs the configured checks and records the outcome.
- A new Pi session receives that progress and continues. The loop stops on completion, a request for human input, a blocker, or an iteration, time, or cost limit.
The default limit is five iterations. Progress and results live in .ralph/; inspect the latest run with ralphworks status .ralph/current. Completion requires the agent's completion signal and, when configured, passing checks. RalphWorks can commit passing iterations with --commit verified; otherwise it leaves changes for you to review.
Use direct text, any plain text or Markdown file, or a small YAML job. Plain task files have no required name or format. Add supporting files or directories with repeatable --context.
For longer work, write small checklist items with observable acceptance criteria; RalphWorks carries progress across fresh sessions without requiring a special PRD format. See the multi-item task example.
ralphworks run ./docs/feature.md --context ./docs/api --max-iterations 8
ralphworks run 'Add CSV export' --check 'npm test' --commit verified--commit verified requires a clean Git worktree and at least one check. The agent does not create commits itself. For reusable checks and limits, see the YAML job format.
For unattended work, start on a dedicated branch and give the loop an independent acceptance check:
ralphworks run ./docs/feature.md --check 'npm test' --commit verified --max-minutes 30 --max-cost-usd 3| Mode | Command | Result |
|---|---|---|
| Host | ralphworks run task.md |
Edits the current worktree. |
| Docker mount | ralphworks run task.md --executor docker |
Edits the mounted worktree. |
| Docker clone | ralphworks run task.md --executor docker-clone --repo owner/repo --ref branch |
Exports a patch from a clean clone. |
| GitHub Actions | ralphworks remote task.md --repo owner/repo --ref branch |
Downloads a patch and run records. |
Docker requires the sandbox image. Clone and remote runs require the task and inputs on the selected branch; they return patches without pushing code. For GitHub Actions, run ralphworks init in the target repository, commit the generated workflow, then configure RALPHWORKS_MODEL and a provider secret as described in the remote setup guide. Continue an unfinished remote run with --resume-from <run-id> on the same unchanged branch.
Docker and remote commands have a 120-minute total deadline, including setup; change it with --total-minutes N. For interrupted local runs, follow the recovery steps before restarting verified commits.
For issue and PR driven work, ralphworks init creates scenario workflows for issue implementation, PRD splitting and serial implementation, dependency promotion, PR review and feedback, branch updates, and architecture proposals. Maintainer labels authorize model runs. Configure a repository check command and a separate token for GitHub delivery.
Full usage and configuration · Architecture · Contributing · Security · License