# ralphex runs a git plan through Claude Code one task at a time

> ralphex is a Go command line tool that drives Claude Code or codex through a markdown plan file, giving each task a fresh session and committing as it goes. Its default executor runs `claude --print`, billed against a separate Anthropic credit pool since June 15, 2026, and its codex executor drops the codex review stage the default pipeline advertises.

**umputun/ralphex** — Extended Ralph loop for autonomous AI-driven plan execution

- Repository: https://github.com/umputun/ralphex
- Website: https://ralphex.com
- Stars: 1,504 · Forks: 131
- Language: Go
- License: MIT
- Published: 2026-10-14 · Updated: 2026-10-14 · Language: en
- Canonical page: https://hysenlabs.com/projects/umputun-ralphex

## A fresh agent session per task, with a commit after each one

ralphex takes one argument, the path to a plan file, and it expects to be started from the root of a git repository. What runs underneath is a loop simple enough to state in a single line: for every task in the plan, spawn a brand new Claude Code session carrying minimal context, execute that task, commit the result, and continue with the next one. That reset is the reason the tool exists, because one long interactive session fills up and the model starts forgetting decisions it made hours earlier. Branch creation is automatic and the branch name is taken from the plan filename, which puts your naming habits into every branch the run creates. Commits land twice over, after each task and again after each review fix, so a review that goes wrong still leaves you with committed work instead of a dirty tree. When the last task closes, the plan file itself is moved to `completed/`.

## The plan file in docs/plans/ is the whole contract

The only input ralphex needs is markdown. A plan carries a Validation Commands block plus task headings with unchecked boxes, and those validation commands are what decide whether a task passed or needs another attempt. This is the shape the README gives:

```markdown
# Plan: My Feature

## Validation Commands
- `go test ./...`

### Task 1: Implement feature
- [ ] Add the new functionality
- [ ] Add tests
```

Drop that file under `docs/plans/` and hand its path to the binary:

```bash
ralphex docs/plans/my-feature.md
```

You should see a branch named after the file, then streamed task output with timestamps and colors, then the plan file relocated somewhere else. Where it lands is the detail worth checking twice: `completed/` is stated on the feature branch under `--worktree`, and for a plain run the destination is not spelled out anywhere. If writing plans by hand is not your preference, `--plan` opens a dialogue with Claude and drafts one for you instead.

## Five review agents, codex, two agents, except under --codex

Review is the expensive half of a run and ralphex spends two passes on it: five review agents, then codex, then two more agents, with the fixes committed afterwards. Each reviewer is a named prompt rather than a different model, resolved through a `{{agent:name}}` template that expands into prompts you wrote, so the review budget is something you edit instead of pick from a list. A careful reader meets a contradiction right after that: `--codex` is described as routing plan creation, task execution, both review phases and finalize through the codex CLI while skipping the external codex review phase. Choose the codex executor and the advertised pipeline is not the pipeline that runs, because the middle stage belongs to the other CLI. Ralphex also states that plans run in four phases plus an optional finalize step, and it never names those four phases.

## claude --print moved onto a separate Anthropic credit pool

The default Claude mode is unattended, and unattended here means ralphex shells out to `claude --print`. Anthropic moved that entry point, the Claude Agent SDK and Claude Code GitHub Actions onto a separate monthly Agent SDK credit pool for subscription users on June 15, 2026, so every unattended ralphex run lands in that pool rather than in ordinary Claude Code usage. Four responses are documented: do nothing, use a skill-based flow inside an interactive Claude Code session built on the `planning` family (`/planning:make`, `/planning:exec`) in umputun/cc-thingz, switch the executor with `--codex`, or point ralphex at a `claude -p` compatible wrapper that emits `stream-json`. The last route is two config keys in `~/.config/ralphex/config` or `.ralphex/config`:

```ini
# in ~/.config/ralphex/config or .ralphex/config
claude_command = /opt/homebrew/bin/fya
claude_args = --dangerously-skip-permissions --output-format stream-json --verbose
```

Homebrew installs that wrapper as umputun/fya, and `command -v fya` is what tells you which absolute path to paste, normally `/opt/homebrew/bin/fya` on Apple Silicon and `/usr/local/bin/fya` on Intel:

```bash
brew install umputun/apps/fya
command -v fya
```

A tmux-backed wrapper takes the same shape with a longer argument list:

```ini
claude_command = /absolute/path/to/agentrun
claude_args = --persist-session --no-session-persistence --dangerously-skip-permissions --output-format stream-json --verbose
```

Those wrappers are called unofficial where they are described, and the docs say plainly to test the exact tool before depending on it.

## The container mounts your .claude, .codex and .gitconfig

Docker is offered as the isolated way to run this, and the compose file in the repository mounts your working tree, your Claude directory, your codex directory, `~/.config/ralphex` and `.gitconfig` into a container, the first four read-only, with 8080 published for the browser dashboard behind `--serve`:

```yaml
services:
  ralphex:
    build: .
    image: ghcr.io/umputun/ralphex:latest
    ports:
      - "8080:8080"
    working_dir: /workspace
    tty: true
```

The part worth reading twice is three lines into the Dockerfile:

```dockerfile
ENV USE_BUILTIN_RIPGREP=0
ENV RALPHEX_DOCKER=1
ENV DISABLE_AUTOUPDATER=1
```

`RALPHEX_DOCKER=1` is commented in the image as the marker used to auto-disable the codex sandbox, so the container marketed as safer autonomous execution switches 1 of the 2 agent sandboxes off inside itself. `DISABLE_AUTOUPDATER=1` stops Claude's own updater, which the surrounding comment explains can never apply here anyway, because npm installs it root-owned while the container runs as app. Refreshing both CLIs needs `RALPHEX_CLI_UPDATE`, and the base image leaves that off by default. Host isolation, yes. Sandbox discipline inside the container, no.

## Worktree isolation is what makes a second plan possible

One checkout is not enough for two plans at once, and `--worktree` is the answer: every run gets its own worktree, which is also the only case where the docs pin down where `completed/` ends up. Output is streamed with timestamps and colors, and detailed logs are kept, so an overnight run can be read back afterwards instead of guessed at from a commit list. Completion can be pushed outward through Telegram, Email, Slack, a webhook or a script of your own. The browser view is not a separate frontend project: the module graph lists `github.com/gorilla/websocket v1.5.3` and `github.com/tmaxmax/go-sse v0.11.0` alongside the CLI, and the end-to-end suite installs Chromium through `github.com/mxschmitt/playwright-go v0.6201.1` before running. That dependency set explains the toolchain floor, since go.mod declares `go 1.26.0` and building from source expects a current Go install rather than a distro package.

## What ralphex does not do, and the two facts framing it

The gaps show up as omission. The four execution phases are never named, so a stalled progress log cannot be mapped to a stage by reading anything the project publishes. Rollback is not covered either: once a task is committed and the plan sits in `completed/`, undoing the run is a git operation you perform by hand. Every step lands as a commit, which rules the tool out wherever branches are protected or a reviewer has to see each change. Build from source and you satisfy `go 1.26.0` yourself. Two facts frame the rest of the decision: the last push was on 2026-09-14, and the three newest tags are v1.7.0, v1.6.1 and v1.6.0. The code is MIT licensed, so shipping the binary inside a product of your own means carrying its copyright notice and licence text along.

## Driving Claude Code by hand, and when that wins

The nearest alternative is not a different tool but the same agent used the way its vendor documents it. The skill-based flow named in the billing guidance stays inside one interactive Claude Code session, with the `planning` commands from umputun/cc-thingz driving the loop and a person approving each step as it happens. The trade is direct: ralphex gives up supervision and gains per-task context isolation, a two-phase review, a named branch and a completion marker; the skill flow keeps you on the subscription path and keeps a human between steps, at the cost of the context reset and the automatic commits. Hand-running the codex CLI is the other comparison, and there the differences are precisely what ralphex adds, since the plan lifecycle, branch creation, review phases, notifications and worktree isolation all live in the wrapper rather than in the agent. If your plan is three edits, none of that machinery earns its place.

## Conclusion

ralphex fits a solo engineer who has a git repository, a written plan and the appetite to hand a coding agent commit rights overnight. It does not fit branches that need per-change approval, work you would have to reverse by hand, or a three-line fix. Nothing published names the 4 execution phases or describes a rollback, so treat the progress log and your own git history as the only record. Before the first unattended run, read what your plan's Validation Commands actually execute, confirm the binary or container can reach the git remote, and check which bill claude --print attaches the run to.

## FAQ

### Does ralphex need a Claude subscription to run a plan?

ralphex itself is free software under the MIT licence, but it drives an external CLI, so you bring your own Claude Code or codex setup. In the default mode it calls claude --print, which since June 15, 2026 is billed against a separate monthly Agent SDK credit pool for subscription users.

### Where do ralphex plan files live and what happens when a plan finishes?

Plans are markdown files kept in docs/plans/, with a Validation Commands block and checkbox task lines. When the last task closes, the file is moved to a completed/ folder, and the branch it ran on is created automatically from the plan filename.

### Can ralphex run two plans at the same time?

Yes, through --worktree, which gives each run its own git worktree instead of sharing one checkout. That is also the only case where the documentation states where the finished plan file lands, namely on the feature branch.

### Does the codex mode run the same review pipeline as Claude Code?

No. --codex routes plan creation, task execution, both review phases and finalize through the codex CLI, and it skips the external codex review phase, so the five agents then codex then two agents pipeline does not apply.

### How do you run ralphex inside Docker?

The repository ships a compose file that builds the local Dockerfile and publishes port 8080 for the browser dashboard, mounting your working tree plus your Claude, codex, ralphex config and git config directories. The image sets RALPHEX_DOCKER=1, which the Dockerfile comments describe as the marker used to auto-disable the codex sandbox.

## Sources

- [License: MIT](https://github.com/umputun/ralphex/blob/master/LICENSE)
- [Project website](https://ralphex.com)
- [README](https://github.com/umputun/ralphex/blob/master/README.md)
- [Releases](https://github.com/umputun/ralphex/releases)
- [umputun/ralphex on GitHub](https://github.com/umputun/ralphex)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/umputun-ralphex