docs

Run a plan, review the branch, keep the trail.

Start with the plan workflow if you are new to RalphTerm. Start with migration if you already use ralphex. The detailed API docs are here too, but the main product path is the unattended plan loop.

Plan workflows CLI reference Migrate from ralphex

Fast path

Install, point RalphTerm at a markdown plan, and let the implementer and reviewer loop run from the terminal.

brew tap RayforceDB/ralphterm https://github.com/RayforceDB/ralphterm
brew install ralphterm

curl -sSf https://ralphterm.rayforcedb.com/install.sh | sh
ralphterm docs/plans/feature.md --review-agent codex

For strict review configuration, use --require-review with either --review-command or --review-agent.

Workflows Plan run, review-only, external-only, retry behavior, transcripts, validation output. CLI reference Every supported flag from --help, grouped by what you are trying to control. Providers Claude, Codex, Copilot, Gemini, and OpenCode command wrappers. Ralphex compatibility Drop-in behavior, accepted flags, supported flags, and deliberate differences. Docker Containerized execution with extra volumes and environment passthrough. Notifications Telegram, Slack, email, and webhook events for unattended runs. Architecture PTY runtime, runner, event store, dashboard, and file handoff design. Security Local trust boundaries, provider credentials, isolation, and operational limits. HTTP API Session and run endpoints, transcripts, progress, and dashboard integration.

Minimal reviewed plan

# Example plan

## Validation Commands
- `cargo test --all`

### Task 1: Add the smallest useful slice
- [ ] Write the failing test first
- [ ] Implement the slice
- [ ] Run the validation command

RalphTerm sends the pending task to the implementation agent, runs validation, then starts the independent reviewer. The reviewer sees the transcript, validation output, and git diff before it can print REVIEW_PASS.

Useful first commands

ralphterm run docs/plans/example.md --dry-run
ralphterm run docs/plans/example.md --workspace-id docs-slice --agent claude
ralphterm run docs/plans/example.md --agent claude --review-agent codex
ralphterm serve

Use dry run to inspect pending tasks, review mode, retry budget, workspace path, and validation commands before agents start. With --workspace-id <id>, RalphTerm creates a managed worktree at .ralphterm/workspaces/<id>, resolves the caller-relative plan path before switching workspace, and does not auto-clean it after the run. In dry-run mode, dry run only previews the workspace path and plan work. Use ralphterm serve when you want the dashboard and live transcripts.