ralph

ralph is a Bun CLI that runs a convention-first autonomous coding loop against the current git repository.

It exposes three commands:

• ralph init
• ralph resume
• ralph [claude|codex|opencode] [once|afk [issue-number]]

Defaults:

• ralph => ralph claude once
• ralph codex => ralph codex once
• ralph codex afk => 100 AFK iterations with no targeted issue
• ralph codex afk 25 => 100 AFK iterations focused on issue #25

Conventions

ralph expects to run inside a git repository and uses these fixed inputs:

• .ralph/prompt.md
• plan.md when present
• open GitHub issues from gh issue list, normalized to ascending issue number before they are added to context
• an AFK-only runnable issue subset derived from the full issue list
• the last 10 commits whose subject starts with RALPH:

When GitHub is reachable, ralph ensures the AFK and HITL labels exist. Automated execution only works from AFK-labeled issues. HITL issues remain visible in context but are not executable until relabeled.

If GitHub issues fail to load and plan.md exists, the run continues with plan.md. If GitHub issues fail to load and plan.md does not exist, the run exits non-zero.

Run transcripts are written to .ralph/runs/. ralph resume reads the newest transcript in that directory and resumes the matching provider session from the stored Ralph metadata. Older legacy transcripts are also supported on a best-effort basis by recovering provider, mode, iteration, session ID, and completion state from the raw log output when possible.

Install

Add GitHub Packages auth to ~/.npmrc:

@amorimdub:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

Install in another repo:

bun add -d @amorimdub/ralph

Run it from that repo:

bunx ralph init
bunx ralph
bunx ralph codex afk 25
bunx ralph resume

If you prefer not to install it locally, Bun's --package flag can run the scoped package directly:

bunx --package @amorimdub/ralph ralph init

Local development

bun install
bun test
bun run typecheck

Prompt scaffold

ralph init creates .ralph/prompt.md with a default backlog policy based on the newer GitHub-issues-first loop. Edit that prompt per repository when you need different verification rules or task-selection logic.

Publishing

This package is published to GitHub Packages under @amorimdub/ralph.

• Pull requests run bun test and bun run typecheck
• Pushes to main publish a unique prerelease build

The publish workflow rewrites the base 0.1.0 version to 0.1.0-main.<run_number>.<run_attempt> before bun publish.