@kimuson/pi-ralph

@kimuson/pi-ralph is a pi package for running a configurable ralph-loop inside pi-coding-agent.

It is not just a single “run tests before finishing” hook. It is a delivery loop for coding-agent work: static verification, AI review, acceptance checks, pull request automation, CI/comment follow-up, and optional merge automation can be composed into one self-running workflow.

The goal is to let an agent continue from implementation to GitHub delivery without repeatedly blocking on a human for routine verification steps.

What ralph-loop does

A ralph-loop can run the following phases in order:

1. Static checks — project-defined commands such as pnpm typecheck, pnpm test, or pnpm gatecheck check.
2. AI checks — optional agent review and natural-language acceptance criteria checks.
3. Completion — stop at edits only, create/update a draft PR, or create/update a ready PR.
4. PR follow-up — optionally wait for CI and keep the task open for the agent to fix failed checks and unresolved PR comments.
5. Merge — optionally merge after follow-up completes, or wait for approval before merging.

Passed AI checks are cached across retries, so the loop can focus on the failing phase instead of restarting everything from scratch.

Setup

Install the package into pi:

pi install npm:@kimuson/pi-ralph

Then configure the default static checks for the repository:

/ralph-configure

/ralph-configure stores only staticChecks in .pi/agent/ralph-loop/default-options.json. Delivery behavior such as PR creation, CI/comment follow-up, and merge automation is selected per command.

For GitHub PR, CI, comment, or merge workflows, the repository must be usable with the GitHub CLI (gh) in the current environment.

Main commands

Preset commands (/ralph-check, /ralph-pr, /ralph-delegate) treat all trailing text as freeform requirement text and forward it to the agent without CLI-style option parsing.

/ralph-loop is also freeform now, but unlike the presets it does not hardcode the final set-ralph-loop payload. Instead, it asks the agent to interpret the request, resolve safe defaults, call set-ralph-loop once, and then continue the actual task work.

/ralph-check

Lightweight verification gate.

Use this when you want ralph-loop to run the configured static checks, and optionally agent-side checks, without touching Git or GitHub delivery.

Trailing text is forwarded as the requirement without option parsing.

Preset:

completion: edit-only
autofix: none
mergeCondition:
  enabled: false
review: false

/ralph-pr

Create a draft PR and keep the loop open for higher-confidence delivery checks.

Use this when you want the agent to prepare a PR but not merge it automatically.

Trailing text is forwarded as the requirement without option parsing.

Preset:

completion: draft-pr
autofix: comment
mergeCondition:
  enabled: false
review: true
acceptanceCriteria: inferred from the requirement when possible

/ralph-delegate

Delegate the whole delivery flow to the agent.

Use this when you want the agent to create a ready PR, fix CI/comment feedback, and merge once the configured follow-up is complete.

Trailing text is forwarded as the requirement without option parsing.

Preset:

completion: pr
autofix: comment
mergeCondition:
  enabled: true
  approved: false
review: true
acceptanceCriteria: inferred from the requirement when possible

/ralph-loop

Natural-language entrypoint for custom combinations.

Use this when the presets are not enough:

/ralph-loop After CI passes and PR approval is present, merge automatically. Review the code too.

/ralph-loop may still receive old CLI-like text such as --autofix comment --merge approved, but that text is no longer machine-parsed by the command itself. The agent reads the request, infers structured parameters, calls set-ralph-loop once, and keeps working.

Safe defaults for unspecified settings:

completion: edit-only
autofix: none
mergeCondition:
  enabled: false
review: false

Option model

Completion

Controls what artifact ralph-loop should produce after static and AI checks pass.

| Mode | Behavior | | ----------- | ----------------------------------------------------------- | | edit-only | Do not commit or create a PR | | draft-pr | Require a clean commit state, then create/update a draft PR | | pr | Require a clean commit state, then create/update a ready PR |

Autofix

Controls how ralph-loop should keep the task open for PR feedback.

| Mode | Behavior | | --------- | ----------------------------------------------------------------------- | | none | Do not perform PR follow-up | | ci | Reopen the task when PR CI is unresolved so the agent can fix it | | comment | Handle PR CI first when present, then reopen for unresolved PR comments |

autofix does not magically patch code by itself. It reports failing CI/comment state back into the agent loop so the agent can continue working until the checks pass.

If no CI checks exist, autofix: ci becomes a no-op and autofix: comment may still proceed to comment follow-up.

Merge condition

Controls whether and when ralph-loop should merge the PR.

mergeCondition:
  enabled: false

Never merge automatically.

mergeCondition:
  enabled: true
  approved: false

Merge automatically after the configured autofix flow completes.

mergeCondition:
  enabled: true
  approved: true

Wait for GitHub PR approval after the configured autofix flow completes, then merge.

When completion: draft-pr is combined with mergeCondition.enabled: true, ralph-loop automatically marks the draft PR as Ready for review before waiting for approval or merging.

Typical workflows

Run local verification only

/ralph-check Refactor the parser

Ask the agent to prepare a draft PR

/ralph-pr Add password reset flow

Delegate implementation through merge

/ralph-delegate Fix the flaky checkout test

Require approval before merge

/ralph-loop After comment follow-up and PR approval, merge the PR automatically. Review the implementation too.

How it works

The package registers pi commands and tools. User-facing preset commands such as /ralph-check, /ralph-pr, and /ralph-delegate translate presets into an exact set-ralph-loop configuration while forwarding their trailing text to the agent as freeform requirement text. /ralph-loop now sends a natural-language handoff that asks the agent to interpret the request, resolve safe defaults and dependencies, call set-ralph-loop once, and then continue the actual task work.

Internally, ralph-loop is stateful: passed review and acceptance checks are reused on later retries, while failed static checks, PR checks, autofix follow-up, or merge conditions keep the task open until the agent fixes them or the loop is explicitly bypassed.

The internal review/completion agents relaunch the pi CLI. If you run pi-ralph inside an embedded SDK host and need to force a specific CLI path, set PI_RALPH_PI_CLI_PATH=/absolute/path/to/pi.

Development

pnpm typecheck        # TypeScript type checking
pnpm test             # Run tests
pnpm lint             # Lint & format check
pnpm gatecheck check  # Run all commit gates

Release

See docs/release.md for the complete release process.

pnpm release # Interactive release (bump, commit, tag, push)

The release uses npm trusted publishing (provenance) via GitHub Actions.

License

MIT