Why ralph?

Claude Code gives you a powerful agent, but the default setup is a blank slate. Repo-level harness conventions — rules, skills, hooks, subagents, verification scripts — have to be invented, maintained, and upgraded by hand, and they drift fast across projects.

ralph ships those conventions as a distributable, upgradable scaffold.

Install

# Homebrew
brew install yoshpy-dev/tap/ralph

# Or install script (verifies SHA256 against GitHub Releases)
curl -fsSL https://raw.githubusercontent.com/yoshpy-dev/ralph/main/scripts/install.sh | sh

Verify:

ralph version
ralph doctor

Quick start

ralph init my-project
cd my-project
ralph doctor                  # environment check (Claude + Codex)

Both agent surfaces are wired up automatically. To make Codex's project-level config and
hooks actually load, run codex trust . once after ralph init. ralph doctor
flags trust gaps so you do not lose hooks silently.

Create your first plan and run the loop inside Claude Code. Prefer the skills
because they create clean-base task worktrees before writing plan artifacts:

/plan

The lower-level ./scripts/new-feature-plan.sh and
./scripts/new-ralph-plan.sh helpers remain available inside an already
resolved task worktree.

In Claude Code, follow the loop with slash commands:

/spec (optional) → /plan → /work (or /loop)
→ /self-review → /verify → /test → /sync-docs
→ /cross-review (optional) → /pr

In Codex, the same flow runs via skill mention syntax (/spec collides with
Codex built-in slash commands — use $skill-name or the /skills menu):

$spec (optional) → $plan → $work (or $loop)
→ $self-review → $verify → $test → $sync-docs
→ $cross-review (optional) → $pr

Before claiming a task is done:

./scripts/run-verify.sh

Features

Commands

Run ralph help <command> for flags.

ralph upgrade interactive diff

When ralph upgrade detects local edits and a template baseline is available, it shows a line-numbered local-vs-template diff and prompts [a]pply template file / [k]eep local file / [e]dit file ?. apply accepts the template for the whole file; keep preserves the current local file as the resolved managed content; edit opens the whole file with Git-style conflict marker blocks (<<<<<<< local, =======, >>>>>>> template (...)) around conflicting regions and requires the markers to be removed before the edit is accepted.

Before file choices are written, ralph upgrade prints an apply summary and asks Apply these changes? [y/N]. Answering no or reaching EOF writes nothing to the target file, baseline cache, or manifest. Normal interactive diff output is rendered inline with the prompt, omits range headers and template/local hash summaries, and does not open a pager. When baseline metadata is missing, v1-style projects fall back to [o]verwrite / [s]kip / [d]iff ? with the diff shown before the choices.

Diff lines carry a right-aligned <old> <new> │ <prefix><content> gutter, and - / + are colorized (red / green; --- / +++ bold) when stdout is a terminal. Set NO_COLOR=1 (or any non-empty value, per no-color.org) to suppress ANSI escapes; piping or redirecting also disables them automatically. --pager applies to ralph upgrade --diff dry-run previews, not to interactive conflict prompts.

What ralph init scaffolds

The philosophy: a map, not a manual. Keep AGENTS.md small, push detail into rules and skills, promote repeated mistakes into hooks, scripts, tests, or CI.

.
├── AGENTS.md                 # vendor-neutral map shared by Claude and Codex
├── CLAUDE.md                 # Claude Code specific guidance (imports AGENTS.md)
├── .claude/
│   ├── settings.json         # hooks, permissions, env
│   ├── hooks/                # deterministic runtime guardrails
│   ├── skills/               # on-demand workflows (plan, work, verify, ...)
│   ├── agents/               # Claude Code subagent definitions
│   └── rules/                # conditional, path-scoped guidance (read by both agents)
├── .codex/
│   ├── config.toml           # model, sandbox, approval, hooks (loads after `codex trust .`)
│   ├── agents/               # Codex role definitions for review/verify/test/docs
│   ├── hooks/                # Codex hook scripts
│   ├── AGENTS.override.md    # Codex-only execution rules
│   └── README.md             # Codex setup and operator guide
├── .agents/
│   └── skills/               # Codex-side skill bodies (mirrors .claude/skills/)
├── docs/
│   ├── specs/                # refined specifications from /spec
│   ├── plans/active/         # plans in flight
│   ├── plans/archive/        # completed plans
│   ├── reports/              # self-review, verify, test artifacts
│   ├── quality/              # definition of done, quality gates
│   └── tech-debt/            # tracked debt
├── packs/languages/          # opt-in language specializations
├── scripts/                  # branch-name.sh, ensure-pr-ready.sh, ensure-pr-title-prefix.sh, run-verify.sh, etc.
├── ralph.toml                # CLI config
└── .github/workflows/        # CI

Operating loop

flowchart LR
    A["/spec<br/>(optional)"] --> B["/plan"]
    B --> C["/work"]
    B --> D["/loop"]
    C --> E["/self-review"]
    D --> E
    E --> F["/verify"]
    F --> G["/test"]
    G --> H["/sync-docs"]
    H --> I["/cross-review<br/>(optional)"]
    I --> J["/pr"]
    J --> K["CI +<br/>human merge"]

/spec is the only manual trigger in the loop; all other steps are auto-invoked. /release is also manual-only but lives outside the loop (repo maintainer use).

1. Spec (manual, optional — /spec) — refine vague requests through decision-tree questioning with recommended answers, codebase exploration, and interactive clarification. Issue-only specs use a temporary clean-base worktree and cleanup; saved specs create a docs/spec PR or hand off to /plan.
2. Plan (auto — /plan) — ensures a clean-base task worktree, then writes a file-backed plan in docs/plans/active/ with acceptance criteria, verify plan, test plan, risks. Selects flow: /work or /loop.
3. Work (auto — /work) or Loop (auto — /loop) — /work resumes the task worktree and implements interactively; /loop runs autonomous parallel slices from the task worktree.
4. Self-review (auto — /self-review) — diff quality artifact.
5. Verify (auto — /verify) — spec compliance + static analysis.
6. Test (auto — /test) — behavioral tests must pass before PR.
7. Sync docs (auto — /sync-docs) — alignment across AGENTS.md / CLAUDE.md / rules / README.
8. Cross-review (auto, optional — /cross-review) — cross-model second opinion via the other agent: Claude Code calls Codex; Codex calls claude -p. Silently skipped if the reviewer side is unavailable.
9. PR (auto — /pr) — structured PR, plan archival, hand-off, and task worktree/local branch cleanup.
10. CI + human merge.

See .claude/rules/post-implementation-pipeline.md for the canonical pipeline order.

Ralph Loop (autonomous parallel execution)

For large tasks that can be split into independent slices, Ralph Loop runs parallel pipelines across multiple Git worktrees. Each slice handles its own lifecycle autonomously (implement → self-review → verify → test → sync-docs → cross-review). Completed slices are sequentially merged into a typed integration branch generated from the plan metadata, then submitted using the manifest PR strategy: grouped PRs by default, with unified or stacked PRs only when explicitly selected.

./scripts/new-ralph-plan.sh --type feat my-feature N/A 3
./scripts/ralph run --plan docs/plans/active/2026-01-01-my-feature/
./scripts/ralph run --plan docs/plans/active/2026-01-01-my-feature/ --pr-strategy unified  # fallback single PR
./scripts/ralph status                  # launches TUI if available
./scripts/ralph status --no-tui         # table output
./scripts/ralph status --json           # JSON output
./scripts/ralph retry <slice-name>
./scripts/ralph abort --slice <slice-name>
./scripts/ralph abort                   # abort all
./scripts/build-tui.sh                  # requires Go 1.22+

Or use the /loop skill inside Claude Code for interactive setup.

The Loop driver is selectable via RALPH_LOOP_DRIVER=claude|codex (or
[loop] driver = "..." in ralph.toml). With driver=codex, per-slice
agent calls go through codex exec and the cross-review reviewer is
inverted to claude -p so the cross-model gate is preserved. See
Ralph Loop recipe
for the full Codex driver workflow.

Safety rails: iteration limits, stuck detection (3 consecutive no-change iterations), Inner/Outer Loop architecture with repair caps, slice timeout detection, signal handlers, hook parity checks. Configure via env vars in scripts/ralph-config.sh.

See docs/recipes/ralph-loop.md for the full guide.

Hooks

.claude/settings.json ships with hooks pre-configured: session start context, prompt-level reminders, Bash guardrails, edit/write verification reminders, tool failure feedback, compaction checkpoints, session end summary. Customize .claude/settings.json directly; use .claude/settings.local.json for personal overrides (gitignored).

Language packs

Core scaffold stays stack-agnostic. Language-specific depth lives in packs/languages/. Starter packs included: typescript/, python/, rust/, golang/, dart/ (Flutter), terraform/ (Terraform / OpenTofu), plus a _template/ for new packs.

Add a pack:

ralph pack add golang
# or
./scripts/new-language-pack.sh golang

Wire it into packs/languages/<name>/verify.sh, .claude/rules/<name>.md, and project build/test tooling.

Portability

ralph ships both Claude Code and Codex surfaces always-on, plus a portable
core that any future agent surface can reuse:

• Portable: AGENTS.md, scripts/, .github/workflows/, packs/languages/, docs/
• Claude-native: CLAUDE.md, .claude/rules/, .claude/skills/, .claude/hooks/, .claude/agents/
• Codex-native: .codex/config.toml, .codex/agents/, .codex/hooks/, .codex/AGENTS.override.md, .codex/README.md, .agents/skills/

scripts/check-skill-sync.sh keeps .claude/skills/ and .agents/skills/ in
lock-step on body, name, description, and implicit-invocation policy. CI fails
on drift so the two agent surfaces cannot quietly diverge.

Known differences between Claude Code and Codex

Adoption order

See docs/roadmap/harness-maturity-model.md. Short version:

1. Map + verify
2. Plan/work/self-review/verify skills
3. Deterministic hooks
4. Path-scoped rules and subagents
5. Worktrees and agent teams for genuinely parallel tasks
6. Evaluator loops and richer observability when complexity earns the cost

Defaults

• Keep AGENTS.md short, CLAUDE.md shorter
• Topic-specific guidance → .claude/rules/
• Workflow-specific guidance → .claude/skills/
• Evidence over confidence
• Do not rely on prose for hard guarantees
• Treat human attention as the scarcest resource

Repository layout (this repo)

.
├── cmd/
│   ├── ralph/                # CLI entrypoint (cobra + go:embed)
│   └── ralph-tui/            # Legacy TUI entrypoint
├── internal/
│   ├── cli/                  # Subcommands
│   ├── scaffold/             # Template embedding + manifest
│   ├── upgrade/              # Diff engine + conflict resolution
│   ├── config/               # ralph.toml parser
│   ├── state/                # Pipeline state reader
│   ├── watcher/              # fsnotify + polling fallback
│   ├── ui/                   # Bubble Tea TUI
│   └── action/               # CLI action executor
├── templates/                # go:embed source (distributed by `ralph init`)
│   ├── base/
│   └── packs/
├── packs/languages/
├── scripts/
├── .goreleaser.yml
└── .github/workflows/

License

MIT