convez.ai
AgenteDevOps & InfraestruturaAvançado
yoshpy-dev

Ralph

yoshpy-dev/ralph

Harness engineering para Claude Code e Codex com scaffold upgradável

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework para construir harnesses de agentes opinionados que funcionam com Claude Code e OpenAI Codex. Oferece scaffolding, hooks determinísticos, revisões baseadas em evidências e execução autônoma paralela (Ralph Loop) para manter convenções consistentes entre projetos.

Instalação

$npx convez-ai yoshpy-dev/ralph

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
8
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 dias
Versão
v8.2.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Scaffolding de projetos com agentes Claude Code padronizados
  • Execução autônoma paralela de múltiplas tarefas (Ralph Loop)
  • Manutenção de convenções e hooks determinísticos entre repositórios

Veredito

Ralph resolve um problema real em equipes que usam Claude Code: manter convenções, hooks e harnesses sincronizados sem derivação manual. É robusto e bem-estruturado, mas exige experiência com pipelines de agentes e CLI para aproveitar todo o potencial.

README

A tradução para o português deste README ainda está na fila.

ralph

Claude Code + Codex harness engineering.

Scaffold, upgrade, and run opinionated agent harnesses that work with both Claude Code and OpenAI Codex from the same project — small always-on maps, on-demand skills, deterministic hooks, evidence-backed reviews, and optional autonomous parallel execution (Ralph Loop).

verify latest release Go version license Homebrew downloads

Why ralph? · Install · Quick start · Features · Commands · Operating loop · Ralph Loop · Language packs · Portability

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.

Bare Claude Coderalph init
Always-on map (AGENTS.md / CLAUDE.md)—✓
On-demand skills (plan, work, verify, loop, ...)manual10+ bundled
Deterministic hooks (mojibake guard, commit-msg, bash guard, ...)manualpre-wired
Evidence-backed pipeline (self-review → verify → test → sync-docs → cross-review)ad hoccanonical order, enforced
Isolated task executionad hoc branchesclean-base task worktrees
Autonomous parallel execution—Ralph Loop (multi-worktree)
Language packs (TS, Python, Rust, Go, Dart, Terraform)—opt-in
Drift management between projectsmanual copyralph upgrade
Cross-agent portability—portable AGENTS.md + scripts

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

Maps, not manualsShort AGENTS.md / CLAUDE.md; push detail into rules and skills, promote repeats into hooks.Canonical pipelineself-review → verify → test → sync-docs → cross-review → pr enforced in standard flow and Ralph Loop.
Deterministic hooksMojibake guard, commit-msg secret scan, Bash guardrails, verification reminders — pre-wired in settings.json.Worktree-first flowSpec, plan, work, and PR artifacts are produced from clean-base task worktrees, with local cleanup after hand-off.
Ralph LoopMulti-worktree autonomous parallel slices, integration branch, grouped PRs by default — orchestrated by ralph run.Language packsTypeScript, Python, Rust, Go, Dart, and Terraform starters (opt-in) with per-language verify.sh and path-scoped rules.
Drift-proof upgradesHash-based ralph upgrade with per-file conflict resolution — keeps N projects aligned as the scaffold evolves.Evidence over proseEvery self-review, verify, test, sync-docs, and cross-review triage pass produces a dated artifact in docs/reports/.
Cross-agent portableAGENTS.md + scripts/ + packs/ stay neutral; .claude/ and .codex/ are agent-specific layers you can stack others beside.Local state, not repo churnWorktree lifecycle records live under git-common-dir, outside tracked files and branch checkouts.

Commands

CommandPurpose
ralph init [name]Scaffold a new project (interactive: language packs, Ralph Loop, TUI).
ralph upgradePull template updates with per-file conflict resolution.
ralph runExecute a Ralph Loop pipeline (orchestrator + per-slice pipelines).
ralph statusLaunch TUI (Lazygit-style 4-pane) or fall back to table/JSON output.
ralph retry <slice>Retry a failed or stuck slice.
ralph abort [--slice <name>]Abort a single slice or all slices.
ralph pack add <lang>Install a language pack.
ralph doctorCheck Claude Code, Codex, hooks, manifest drift, language packs.
ralph versionShow semver + commit + build date.

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

ConcernClaude CodeCodex
Skill invocation/skill-name slash command$skill-name mention or /skills menu — /skill-name collides with Codex built-ins (/plan, /review, /status)
Subagents in /work post-implTask(subagent_type=...) calls.codex/agents/ custom agents with the same phase roles
Structured promptsAskUserQuestionnumbered stdin prompt
Cross-model reviewercalls codex exec reviewcalls claude -p with adversarial reviewer prompt
Permission policypermission_mode = "auto"sandbox_mode = "workspace-write" + approval_policy = "on-request"
Config trustalways loads .claude/settings.jsononly loads .codex/config.toml after codex trust . AND [features] hooks = true

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

Ver o original no GitHub

Bom para

Relacionados