Providers

RalphTerm runs the official Anthropic Claude Code CLI by default — no wrapper needed. For other providers (Codex, Copilot, Gemini, OpenCode), RalphTerm ships small POSIX wrapper scripts in scripts/wrappers/. Pick one with --agent <name>; --claude-command still wins when both are set. Each provider owns its own auth and credentials.

claude — default

The default provider. Running ralphterm <plan> with no --claude-command and no [agent] provider invokes the claude binary directly inside a PTY.

# install (one of)
npm install -g @anthropic-ai/claude-code
# or download from https://github.com/anthropics/claude-code

# auth — either interactive or env
claude login
# or:
export ANTHROPIC_API_KEY=sk-ant-...

# CLI usage — no wrapper, no flags needed
ralphterm docs/plans/feature.md
ralphterm --tasks-only docs/plans/feature.md

codex

Install OpenAI Codex CLI and log in once. Then either use --agent codex or set agent = codex in config.

# install
npm install -g @openai/codex
codex login

# environment
export OPENAI_API_KEY=sk-...
export CODEX_HOME=$HOME/.codex     # optional override

# config snippet (~/.config/ralphex/config.json)
{
  "agent": "codex",
  "claude_command": "scripts/wrappers/codex.sh"
}

# CLI usage
ralphterm --agent codex docs/plans/feature.md
ralphterm --claude-command scripts/wrappers/codex.sh docs/plans/feature.md

copilot

Install the GitHub Copilot CLI and authenticate. The wrapper translates RalphTerm's PTY input/signals into Copilot-specific behavior.

# install
gh extension install github/gh-copilot

# environment
export GITHUB_TOKEN=ghp_...        # or rely on gh auth login

# config snippet
{
  "agent": "copilot",
  "claude_command": "scripts/wrappers/copilot.sh"
}

# CLI usage
ralphterm --agent copilot docs/plans/feature.md

gemini

Install the Google Gemini CLI; auth via gcloud or API key.

# install
npm install -g @google/gemini-cli
gemini auth                         # or: export GEMINI_API_KEY=...

# environment
export GEMINI_API_KEY=...

# config snippet
{
  "agent": "gemini",
  "claude_command": "scripts/wrappers/gemini.sh"
}

# CLI usage
ralphterm --agent gemini docs/plans/feature.md

opencode

OpenCode is the open-source terminal-native agent; the wrapper drives it over PTY just like Claude Code.

# install
curl -fsSL https://opencode.ai/install | bash

# environment
export OPENCODE_API_KEY=...         # only if your backend requires it

# config snippet
{
  "agent": "opencode",
  "claude_command": "scripts/wrappers/opencode.sh"
}

# CLI usage
ralphterm --agent opencode docs/plans/feature.md

Mixing implementation and review providers

Run implementation on one provider and review on another. The reviewer runs in its own PTY after validation.

ralphterm docs/plans/feature.md \
  --agent claude \
  --external-review-tool=codex \
  --review-model gpt-5-codex