---
slug: "kimuson-pi-ralph"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/d-kimuson/pi-ralph@main/README.md"
repo: "https://github.com/d-kimuson/pi-ralph"
source_file: "README.md"
branch: "main"
---
# @kimuson/pi-ralph

`@kimuson/pi-ralph` is a pi package for running a configurable **ralph-loop** inside [`pi-coding-agent`](https://github.com/earendil-works/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:

```bash
pi install npm:@kimuson/pi-ralph
```

Then configure the default static checks for the repository:

```text
/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:

```yaml
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:

```yaml
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:

```yaml
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:

```text
/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:

```yaml
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.

```yaml
mergeCondition:
  enabled: false
```

Never merge automatically.

```yaml
mergeCondition:
  enabled: true
  approved: false
```

Merge automatically after the configured `autofix` flow completes.

```yaml
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

```text
/ralph-check Refactor the parser
```

### Ask the agent to prepare a draft PR

```text
/ralph-pr Add password reset flow
```

### Delegate implementation through merge

```text
/ralph-delegate Fix the flaky checkout test
```

### Require approval before merge

```text
/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

```bash
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](https://github.com/d-kimuson/pi-ralph/blob/HEAD/docs/release.md) for the complete release process.

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

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

## License

MIT