RalphTerm

A safer replacement for brittle one-shot AI CLI automation.

RalphTerm solves a concrete problem: many autonomous coding stacks depend on one-shot CLI prompt flags. That path gets fragile when the CLI asks for approval, changes output format, needs follow-up input, hits auth, or moves more behavior into the interactive terminal. RalphTerm runs Claude Code, Codex, and future terminal agents inside real PTYs, then gives orchestration systems a clean API around that session.

The point is not to bypass the vendors. The point is to stop pretending the terminal is not there. The official CLI still owns login, rate limits, safety prompts, and account identity. RalphTerm owns session control, streaming, transcripts, signals, and approvals.

Links

• Website: ralphterm.rayforcedb.com
• Documentation: ralphterm.rayforcedb.com/docs/
• Social preview: assets/social-preview.png
• Milestone 1: docs/milestones/m1-autonomous-engineering.md
• Security model: docs/security.md

Why RalphTerm exists

AI coding tools are becoming interactive terminal products. Automation built around non-interactive prompt mode is fragile. RalphTerm takes the durable path: run the real CLI in a real terminal and build a reliable control plane around it.

What RalphTerm does today

• Replaces one-shot prompt-mode execution with one isolated PTY session per agent run.
• Supports Claude Code and Codex as first-class agents.
• Sends prompts and follow-up input as terminal keystrokes.
• Streams raw terminal output over WebSocket.
• Keeps transcripts and status for every session.
• Detects workflow signals such as COMPLETED, FAILED, PLAN_READY, QUESTION, and REVIEW_DONE.
• Exposes REST controls for create, input, resize, cancel, status, transcript, and events.
• Binds to 127.0.0.1 by default because the API controls local terminals.

Quick start

git clone git@github.com:RayforceDB/ralphterm.git
cd ralphterm
cargo run -- serve --bind 127.0.0.1:7878

Health check:

curl http://127.0.0.1:7878/health

Expected:

{"ok":true}

Current API

GET  /health
POST /v1/sessions
GET  /v1/sessions/:id
POST /v1/sessions/:id/input
POST /v1/sessions/:id/resize
POST /v1/sessions/:id/cancel
GET  /v1/sessions/:id/events
GET  /v1/sessions/:id/transcript

Deterministic smoke test using /bin/sh as the command override:

ID=$(curl -sS -X POST http://127.0.0.1:7878/v1/sessions \
  -H 'content-type: application/json' \
  -d '{
    "agent":"claude",
    "command":"/bin/sh",
    "args":["-lc","read line; printf \"%s\\n\" \"$line\"; echo COMPLETED"],
    "prompt":"hello from ralphterm"
  }' | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])')

curl http://127.0.0.1:7878/v1/sessions/$ID
curl http://127.0.0.1:7878/v1/sessions/$ID/transcript

Manual real CLI smoke test for ralphterm run:

ralphterm run docs/plans/example.md --dry-run
ralphterm run docs/plans/example.md --agent claude

Start with --dry-run to see the pending tasks and validation commands without starting an agent, editing the plan, writing progress logs, or committing. Run the real CLI command only after the official Claude Code CLI is installed, authenticated, and works interactively as claude in your shell. RalphTerm launches the interactive CLI in a PTY and sends terminal input; it does not use claude -p, --print, or any one-shot prompt mode. Use --agent codex to run the same workflow with an authenticated interactive codex CLI. The lower-level --agent-command <cmd> option remains available for tests and custom command wrappers.

Milestone 1

Milestone 1 is to ship a complete autonomous engineering workflow on top of RalphTerm's PTY core:

• task intake and planning
• isolated workspaces
• multi-agent execution
• review loops
• approval queue
• status dashboard
• notifications
• transcript and event audit trail
• final patch and summary artifacts
• local-first API and CLI

See docs/milestones/m1-autonomous-engineering.md.

Documentation

• docs/product.md — product positioning and principles
• docs/api.md — current API contract
• docs/architecture.md — daemon, PTY runtime, events, storage
• docs/security.md — compliance and safety model
• docs/getting-started.md — local development quickstart
• docs/workflows.md — run and review workflows
• site/ — static landing website and hosted docs

Development

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

Compliance stance

RalphTerm is a terminal multiplexer and orchestration layer, not a protocol bypass. It launches official user-installed CLIs in PTYs, leaves auth and rate limits to those CLIs, and requires explicit user-configured approval policy for automation. It does not emulate private APIs, store provider credentials, alter account identity, or bypass interactive safety prompts by default.

License

MIT. See LICENSE.