A local loop for small, reviewable agent work.
Plans stay in Markdown with simple metadata. No service, database, or private backlog format.
Later plans wait until their prerequisites are marked done and archived.
Every run writes a ralph-summary.md with records, warnings, failures, and simplify results.
Ralph is not a generic scheduler. It is a narrow CLI for people who already plan implementation work in docs and want Codex to drain that queue safely enough to inspect afterward.
Copy, preview, run.
Start with the bundled queue, dry-run it, then process one plan before letting Ralph drain the rest.
pnpm add --global github:Anderbone/ralph-loop
cp -R examples/doc-plan ~/plans/my-project
ralph --repo ~/work/my-project --plans ~/plans/my-project --dry-run
ralph --repo ~/work/my-project --plans ~/plans/my-project --once
status: planned
created_at: 2026-05-21T12:00:00.000Z
updated_at: 2026-05-21T12:00:00.000Z
done_at: none
independent: yes
dependencies: none
# Add Health Endpoint
## Goal
Add a small health endpoint.
## Acceptance Criteria
- Exposes GET /health.
- Returns a successful response.
- Relevant tests pass.Plans are readable before and after a run.
planned items run when every dependency is done.
blocked items require a reason and stay in the active queue.
Completed plans move to done/, where future dependencies can still resolve them.
Use it when the queue is trusted.
Ralph intentionally invokes Codex without approval prompts so a queue can keep moving. Preview first, keep plans small, and read the summary after each run.