OpenRalph

OpenRalph is a small opencode plugin and CLI for running a Ralph-loop-style workflow autonomously in a Docker container.

Phases

OpenRalph works in three phases:

• define: interactive - Work with the agent to ideate and clarify your idea. This produces a .ralph/specs/* artifact.
• plan: autonomous - Consumes .ralph/specs/* and breaks requirements into individual tasks. This produces .ralph/plans/IMPLEMENTATION_PLAN.md.
• build: autonomous - Reads .ralph/plans/IMPLEMENTATION_PLAN.md and handles one task at a time with fresh context for each child run.

Quick Start

Install the npm package @john-ezra/open-ralph through opencode's plugin installer:

1. Open opencode in the target project.
2. Run Install plugin from the command palette/plugins UI.
3. Enter @john-ezra/open-ralph at the package name prompt.
4. Leave scope as local, or press Tab to toggle to global.
5. Run /ralph and pick a mode to start your first loop.

CLI installation equivalent:

opencode plugin @john-ezra/open-ralph
opencode plugin --global @john-ezra/open-ralph

Direct package execution with bunx @john-ezra/open-ralph ... or an installed openralph binary requires Bun.

Usage

Run /ralph from the opencode TUI and choose a mode, or use the CLI entrypoints:

• Design (TUI) / define phase: starts a requirements conversation and guides work toward planning-ready .ralph/specs/*.md files.
• Plan (TUI) / openralph plan: runs fresh planning iterations until the plan is stable, updating .ralph/plans/IMPLEMENTATION_PLAN.md and committing it when planning reports completion.
• Build (TUI) / openralph build: requires a clean worktree, runs fresh build iterations one task and one commit at a time, implementing one plan item and running validation each iteration.
• openralph docker build: builds a local/custom runtime image.

Flags (all optional):

openralph plan [max] [--model <provider/model>] [--no-docker]
openralph build [max] [--model <provider/model>] [--push] [--no-docker]
openralph docker build [--tag <image>] [--no-cache]

Plan and Build collect the same args in the TUI as on the CLI. Leave args empty for the default unlimited loop, or enter 1 for a bounded smoke test. In the TUI, use the output dialog Cancel action to stop an active loop; in CLI/headless runs, use Ctrl+C.

Use a dedicated branch or disposable clone for autonomous Ralph runs. Build --push works only in host mode; Docker mode rejects it so you can review local commits before pushing.

Project Setup

OpenRalph keeps all of its per-project artifacts under a single .ralph/ directory at the project root:

.ralph/
  specs/                     # behavioral requirements (Design output, Plan input)
  plans/IMPLEMENTATION_PLAN.md  # the active work queue (Plan output, Build input)
  runs/                      # per-run audit/debug artifacts (ignored)

OpenRalph works best when the target project keeps a small set of clear disk artifacts:

• .ralph/specs/*: behavioral requirements for Plan to compare against the codebase.
• AGENTS.md: operational notes, especially build/test/lint/typecheck commands and project conventions.
• .ralph/plans/IMPLEMENTATION_PLAN.md: the active work queue for the current Ralph initiative. Plan creates or updates it; Build consumes and maintains it across iterations. When the initiative is complete, delete, reset, or replace it before starting unrelated Ralph work.
• Validation: tests, typecheck, lint, and browser checks for UI work when practical.

Requirements vs. tasks

Specs and the plan use distinct, non-interchangeable identifiers:

• Requirement (R#) lives in .ralph/specs/* and is a behavioral acceptance criterion — what must be true. A spec numbers its requirements R1, R2, ... Rn.
• Task (T#) lives in .ralph/plans/IMPLEMENTATION_PLAN.md and is an actionable unit of work sized for one build iteration — what to do. Plan numbers tasks T1, T2, ... Tn in priority order.

One task may satisfy several requirements, so each plan task names what it covers (e.g. T1 (satisfies R1-R4, R7)). A coherent deliverable that satisfies R1-R7 in a single edit is one task, not seven, and each Build iteration completes exactly one task.

Keep setup lean. If output is poor, improve validation or split plan items before adding prompt complexity.

Configuration

Manual config is only needed when bypassing opencode's plugin installer or editing options directly. Add @john-ezra/open-ralph to both server and TUI config when needed.

• Server config: opencode.json with schema https://opencode.ai/config.json.
• TUI config: tui.json with schema https://opencode.ai/tui.json.
• Supported options: defineModel, planModel, buildModel, docker.enabled, docker.image, and docker.maskEnv.

Option sources are resolved per run: OPENRALPH_OPTIONS_JSON (when set) is the complete configuration; otherwise options passed by the TUI plugin (tui.json) win per key over the project opencode.json plugin entry, which fills in the rest. defineModel for Design is read from the TUI plugin options only.

Model precedence is:

command --model -> OpenRalph config -> current TUI session model for /ralph Plan/Build -> opencode default

Direct CLI/headless runs can pass plugin options through OPENRALPH_OPTIONS_JSON. Without that env var, openralph plan/build uses defaults: Docker enabled, .env* masking enabled, and ghcr.io/john-ezra/open-ralph:<installed-package-version> as the runtime image.

Restart opencode after installing or changing opencode.json, tui.json, or plugin files.

Docker Mode

Docker mode is the default for Plan and Build from /ralph, openralph plan, and openralph build. To run directly on the host, pass --no-docker or set docker.enabled to false.

When docker.image is omitted, OpenRalph uses ghcr.io/john-ezra/open-ralph:<installed-package-version>. It pulls that default image if missing, runs the container with --pull=never, and refuses stale or unlabelled images. Custom images are user-managed and are not pulled automatically.

On Windows, run OpenRalph from WSL2 with Docker Desktop's WSL integration enabled.

Build the default local image when you need an offline or project-custom runtime:

bunx @john-ezra/open-ralph docker build

If openralph is already on PATH, you can use:

openralph docker build

Use a custom tag when extending the image:

bunx @john-ezra/open-ralph docker build --tag openralph:rust

Example extension:

FROM openralph:local

USER root

RUN apt-get update \
  && apt-get install -y --no-install-recommends cargo rustc \
  && rm -rf /var/lib/apt/lists/*

USER opencode

Build it with Docker, then set docker.image to the custom tag:

docker build -f Dockerfile.openralph -t openralph:rust .

The default image supports linux/amd64 and linux/arm64. It includes opencode, Bun, Node 22, npm/npx/corepack, Git, Bash, curl, Python 3, native build tools, ripgrep, browser tooling, and screenshot-friendly fonts.

Security

OpenRalph Plan and Build child iterations run opencode run --dangerously-skip-permissions. Treat agent actions as untrusted.

Docker mode reduces host filesystem exposure, but it is not a formal sandbox. The container can read and write the mounted repository, including .git; can read the mounted OpenCode auth file; and has unrestricted network egress. Docker mode masks files whose basename starts with .env (case-insensitive), except .env.example, .env.sample, .env.template, and .env.dist. Symlinked .env* files are masked by masking their resolved target when it lives inside the repository; targets outside the repository are not mounted into the container. The scan skips .git and node_modules and does not follow directory symlinks. It does not mask other in-repo secrets such as .npmrc, private keys, cloud credentials, or service-account JSON.

Host mode runs child iterations directly on your machine with inherited environment variables, host filesystem access, and unrestricted network access. Use it only when you intentionally want that behavior.

Review changes before running host tools or pushing. Agent-written repository hooks or Git config can affect later host-side Git commands.

Run Artifacts

Plan and Build write audit/debug artifacts under .ralph/runs/openralph-<phase>-YYYYMMDD-HHMMSS/:

.ralph/runs/openralph-build-YYYYMMDD-HHMMSS/
  ralph.log
  iter-001.jsonl
  iter-001.txt

Artifacts are not loop state. Fresh child iterations rely on .ralph/specs/*, AGENTS.md, .ralph/plans/IMPLEMENTATION_PLAN.md, and the bundled prompts. Run artifacts may contain terminal output, command details, paths, and model text; do not commit or share them blindly.

Development

For local development against this checkout, use relative file plugin specs:

opencode.json plugin: ./src/plugin.ts
tui.json plugin: ./src/tui.ts

Validate changes with:

bun install
bun run validate