Skip to content

getting-started.md

Latest commit

 

History

History
138 lines (94 loc) · 4.01 KB

getting-started.md

File metadata and controls

138 lines (94 loc) · 4.01 KB

Getting Started

RalphTerm is a drop-in replacement for ralphex. The fastest way to learn it is to point it at an existing plan and run the same command you would run with ralphex.

Install

From source:

git clone git@github.com:RayforceDB/ralphterm.git
cd ralphterm
cargo install --path .

This installs both ralphterm and the bundled ralphex alias. Confirm:

ralphterm --version
ralphex --version

If you only want to run from the checkout without installing, cargo build --release produces ./target/release/ralphterm and ./target/release/ralphex.

Point at a plan

Plans are markdown files with unchecked task items and a ## Validation Commands block. A minimal example:

# 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

Save it as docs/plans/example.md (or anywhere you like).

Run it (ralphex-style)

The drop-in command form is the same as ralphex:

ralphex --tasks-only docs/plans/example.md

That runs only the implementation phase: it skips the review gate, sends each pending task to the agent inside a real PTY, runs the validation commands, marks the task [x] on success, and commits a local checkpoint (unless you pass --no-commit).

ralphterm is the same binary under a different name:

ralphterm --tasks-only docs/plans/example.md

Add the review gate

Default (full) mode requires an independent reviewer. Configure one with --external-review-tool=custom --custom-review-script <cmd>:

ralphterm \
  --external-review-tool=custom \
  --custom-review-script "codex exec review-task" \
  docs/plans/example.md

After implementation succeeds and validation passes, the reviewer sees the transcript, validation output, and git diff in a fresh PTY along with the task text. It must print REVIEW_PASS for RalphTerm to mark the task [x] and commit. A REVIEW_FAIL triggers a single implementation retry with the reviewer's feedback; a second failure leaves the task unchecked.

The same gate can be persisted in ~/.config/ralphex/config:

external_review_tool = custom
custom_review_script = codex exec review-task

Native subcommand path

For users who want the explicit RalphTerm interface, the run subcommand exposes the same behavior with named flags:

ralphterm run docs/plans/example.md --dry-run
ralphterm run docs/plans/example.md --agent claude \
  --require-review \
  --review-command "codex exec review-task"

--dry-run prints pending tasks, review mode, retry budget, and validation commands without starting an agent or editing the plan.

To isolate the run in a managed git worktree, add --workspace-id <id>:

ralphterm run docs/plans/example.md --workspace-id docs-slice --agent claude

RalphTerm creates .ralphterm/workspaces/<id>, resolves the caller-relative plan path inside the worktree, and runs from there. It does not auto-clean the worktree; remove it later with ralphterm workspace cleanup <id>.

Start the daemon

For the REST + WebSocket API:

ralphterm serve --bind 127.0.0.1:7878
curl http://127.0.0.1:7878/health

Expected:

{"ok":true}

The ralphex-compatible --serve flag also works:

ralphex --serve --port 7878 --host 127.0.0.1

See docs/api.md for the API contract.

Where to go next

Development checks

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all