Migrate from ralphex

RalphTerm is a drop-in replacement for ralphex. Same flags, same plan files, same config directories. This guide walks the five-step swap.

1. Install ralphterm

Build from source or install a release binary. The build produces two binaries: ralphterm and ralphex. They share the same code path; the second is an alias.

git clone git@github.com:RayforceDB/ralphterm.git
cd ralphterm
cargo build --release
# install both binaries somewhere on PATH
install -m 0755 target/release/ralphterm /usr/local/bin/ralphterm
install -m 0755 target/release/ralphex    /usr/local/bin/ralphex

2. Point your scripts at ralphex (the alias) or ralphterm

Existing scripts that invoke ralphex --tasks-only ... keep working unchanged because the ralphex binary alias accepts the same flags. If you prefer the new name, change the invocation to ralphterm. Both run the same compatibility parser.

# Existing ralphex script - keep it as-is, just install the new binary
ralphex --tasks-only --claude-command claude docs/plans/feature.md

# Or rename the call to ralphterm with no other changes
ralphterm --tasks-only --claude-command claude docs/plans/feature.md

3. Keep ~/.config/ralphex/

RalphTerm reads the same config directories ralphex did. The default global config dir is ~/.config/ralphex/; the project-local override is .ralphex/. --config-dir and RALPHEX_CONFIG_DIR still work. Existing prompts, agents, claude_command, claude_args, task/review model split, codex/external review config, timeouts, worktree settings, watch directories, plan-completion move config, and notify settings are read directly.

$ ls ~/.config/ralphex/
config.json   prompts/   agents/

$ ls .ralphex/
config.json   progress/

4. Confirm the review gate works

Verify both modes with a small plan. The first command uses --tasks-only for a no-review smoke pass; the second runs the full reviewed loop so you see that the independent reviewer is required before progress is committed.

# tasks-only mode (review skipped)
ralphterm --tasks-only docs/plans/example.md

# full mode with the default review gate
ralphterm docs/plans/example.md \
  --claude-command claude \
  --external-review-tool=codex

If you previously used --external-review-tool=custom --custom-review-script ./review.sh in ralphex, it maps directly onto RalphTerm's independent review command. Without a reviewer, full mode fails before agent execution instead of silently claiming acceptance.

5. (Optional) Add notifications, Docker, worktrees, wrappers

These surfaces are also drop-in compatible:

• Notifications: configure Telegram, Slack, Email, or Webhook under [notify]; CLI overrides --notify-telegram-token, --notify-slack, --notify-webhook, --notify-on still apply. See notifications.
• Docker isolation: --docker --docker-image ralphterm:latest runs the agent and reviewer inside a container. Honors RALPHEX_EXTRA_VOLUMES and RALPHEX_EXTRA_ENV. See docker.
• Worktrees: --worktree --branch <name> creates isolated git worktrees per run. Branch defaults to the plan filename slug.
• Alternate providers: --agent codex|copilot|gemini|opencode picks a wrapper script in scripts/wrappers/. See providers.

What changed under the hood

RalphTerm enforces the original ralphex semantic without any wiggle room: implementation COMPLETED is not acceptance. Acceptance requires validation plus independent review until reviewers find zero actionable issues. Use --review-patience and --max-iterations to tune the loop; use --tasks-only to skip review intentionally.