Backends

Ralph supports multiple AI CLI backends. This guide covers setup and selection.

Supported Backends

Auto-Detection

Ralph automatically detects installed backends:

ralph init
# Auto-detects available backend

Detection order (first available wins):

1. Claude
2. Kiro
3. Gemini
4. Codex
5. Amp
6. Copilot
7. OpenCode
8. Pi

Explicit Selection

Override auto-detection:

# Via CLI
ralph init --backend kiro
ralph run --backend gemini

# Via config
# ralph.yml
cli:
  backend: "claude"

Backend Setup

Each backend below includes:

• Install instructions
• Auth & env vars (API keys or login)
• Hat YAML configuration
• ralph doctor validation notes

Backend names (used in YAML and CLI flags): claude, kiro, gemini, codex, amp, copilot, opencode, pi.

Claude Code (claude)

The recommended backend with full feature support.

# Install
npm install -g @anthropic-ai/claude-code

# Authenticate
claude login

# Verify
claude --version

Auth & env vars:

• claude login (preferred)
• ANTHROPIC_API_KEY (used by ralph doctor auth hints)

Hat YAML:

hats:
  planner:
    backend: "claude"

Doctor checks:

• claude --version must succeed
• Warns if ANTHROPIC_API_KEY is missing

Features:

• Full streaming support
• All hat features
• Memory integration

Kiro (kiro)

Amazon/AWS AI assistant.

# Install
# Visit https://kiro.dev/

# Verify
kiro-cli --version

Auth & env vars:

• Complete Kiro CLI authentication (AWS/SSO) per Kiro docs
• KIRO_API_KEY (optional; used by ralph doctor auth hints)

Hat YAML:

hats:
  coder:
    backend: "kiro"

Kiro agent selection (optional):

hats:
  reviewer:
    backend:
      type: "kiro"
      agent: "codex"

Doctor checks:

• kiro-cli --version must succeed
• Warns if KIRO_API_KEY is missing (OK if you authenticated via CLI)

Gemini CLI (gemini)

Google's AI CLI.

# Install
npm install -g @google/gemini-cli

# Configure API key

# Verify
gemini --version

Auth & env vars:

• GEMINI_API_KEY (used by ralph doctor auth hints)

Hat YAML:

hats:
  analyst:
    backend: "gemini"

Doctor checks:

• gemini --version must succeed
• Warns if GEMINI_API_KEY is missing

Codex (codex)

OpenAI's code-focused model.

# Install
# Visit https://github.com/openai/codex

# Configure

# Verify
codex --version

Auth & env vars:

• OPENAI_API_KEY or CODEX_API_KEY (either satisfies ralph doctor auth hints)

Hat YAML:

hats:
  coder:
    backend: "codex"

Doctor checks:

• codex --version must succeed
• Warns if neither OPENAI_API_KEY nor CODEX_API_KEY is set

Amp (amp)

Sourcegraph's AI assistant.

# Install
# Visit https://github.com/sourcegraph/amp

# Verify
amp --version

Auth & env vars:

• Authenticate via amp CLI per Sourcegraph docs
• No auth env vars are checked by ralph doctor for Amp

Hat YAML:

hats:
  helper:
    backend: "amp"

Doctor checks:

• amp --version must succeed

Copilot CLI (copilot)

GitHub's AI assistant.

# Install
npm install -g @github/copilot

# Authenticate
copilot auth login

# Verify
copilot --version

Auth & env vars:

• Authenticate via Copilot CLI (copilot auth login or gh auth login)
• No auth env vars are checked by ralph doctor for Copilot

Hat YAML:

hats:
  reviewer:
    backend: "copilot"

Doctor checks:

• copilot --version must succeed

OpenCode (opencode)

Community AI CLI.

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

# Verify
opencode --version

Auth & env vars:

• Set one of: OPENCODE_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY
• OpenCode can proxy multiple providers; use the env var matching your provider

Hat YAML:

hats:
  strategist:
    backend: "opencode"

Doctor checks:

• opencode --version must succeed
• Warns if none of OPENCODE_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY are set

Pi (pi)

Multi-provider AI coding assistant.

# Install
npm install -g @mariozechner/pi-coding-agent

# Verify
pi --version

Auth & env vars:

• Set one of: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, or any supported provider key
• Pi routes to the provider specified via --provider (default: google)
• Pass API key explicitly with --api-key or rely on provider-specific env vars

Hat YAML:

hats:
  coder:
    backend: "pi"

Pi provider selection (optional):

hats:
  coder:
    backend:
      type: "pi"
      args: ["--provider", "anthropic", "--model", "claude-sonnet-4"]

Doctor checks:

• pi --version must succeed
• Warns if no provider API key is set

Per-Hat Backend Override

Different hats can use different backends:

hats:
  planner:
    backend: "claude"  # Use Claude for planning
    triggers: ["task.start"]
    instructions: "Create a plan..."

  coder:
    backend: "kiro"    # Use Kiro for coding
    triggers: ["plan.ready"]
    instructions: "Implement..."

Custom Backends

For unsupported CLIs, use the custom backend:

cli:
  backend: "custom"
  custom_command: "my-ai-cli"
  prompt_mode: "arg"  # or "stdin"

Prompt modes:

Backend Comparison

Troubleshooting

Backend Not Found

ERROR: No AI agents detected

Solution:

1. Install a supported backend
2. Ensure it's in your PATH
3. Test directly: claude -p "test" or pi -p "test"

Authentication Failed

ERROR: Authentication required

Solution:

# Claude
claude login

# Copilot
copilot auth login

# Gemini - set API key

# Pi - set provider API key

If the CLI is already authenticated but ralph doctor still warns, ensure the expected env vars above are set (doctor checks are hints, not hard failures).

Wrong Backend Used

# Force specific backend
ralph run --backend claude

# Or set in config
cli:
  backend: "claude"

Backend Hanging

Some backends need interactive authentication on first run:

# Run backend directly first
claude -p "test"

# Then use with Ralph
ralph run

Best Practices

1. Pick one primary backend — Consistency helps
2. Test backend directly — Before using with Ralph
3. Use per-hat overrides sparingly — Can complicate debugging
4. Keep backends updated — New features, bug fixes

Next Steps

• Configure Presets for your workflow
• Learn about Cost Management
• Explore Writing Prompts