RalphTUI

Factory Droid Agent

Run Factory Droid CLI (droid) as an autonomous agent in Ralph TUI.

Factory Droid Agent

The Factory Droid agent plugin integrates with the droid CLI so Ralph TUI can execute tasks with Factory Droid alongside Claude Code and OpenCode.

INFO

Factory Droid supports tracing of tool calls, costs, and execution events. Subagent tracing is not currently supported.

Prerequisites

Install the Factory Droid CLI and authenticate:

Bash
# Install droid and ensure it is on your PATH
# (Follow Factory Droid installation instructions)
 
droid --version

Set FACTORY_API_KEY in your environment (or run droid auth).

Basic Usage

Run with Factory Droid

Use the --agent droid flag:

Bash
ralph-tui run --prd ./prd.json --agent droid

Configuration

Shorthand Config

Basic configuration:

TOML
# .ralph-tui/config.toml
agent = "droid"
 
[agentOptions]
model = "claude-opus-4-5-20251101"
reasoningEffort = "medium"
enableTracing = true

Full Config

For advanced control:

TOML
[[agents]]
name = "droid"
plugin = "droid"
default = true
 
[agents.options]
model = "claude-opus-4-5-20251101"
reasoningEffort = "high"
enableTracing = true

Options Reference

OptionTypeDefaultDescription
modelstring-Model name passed to the droid CLI via --model
reasoningEffortlow | medium | high-Reasoning effort level passed via --reasoning-effort
enableTracingbooleantrueEnables JSONL stream output (--output-format stream-json)

Models and Reasoning Effort

Factory Droid supports passing a model name and reasoning effort level. Configure via agentOptions and refer to the official list of available models:

TOML
[agentOptions]
model = "claude-opus-4-5-20251101"
reasoningEffort = "high"

Output Tracing

When enableTracing = true, Ralph TUI requests JSONL stream output and parses:

  • Tool calls and arguments
  • Assistant messages and result events
  • Error/status events
  • Cost metrics (tokens, cache stats, USD)

Toggle tracing in the TUI:

  • Press t to cycle tracing detail levels
  • Press u to show/hide the output panel

Autonomous Operation

Ralph TUI runs Factory Droid in fully autonomous mode with --skip-permissions-unsafe. This is required because ralph-tui cannot relay interactive prompts back to droid.

INFO

Factory Droid will execute tool actions without asking for confirmation. Review tasks carefully before starting execution.

How It Works

Ralph TUI builds a command similar to:

Bash
droid exec \
  --model claude-opus-4-5-20251101 \
  --reasoning-effort high \
  --skip-permissions-unsafe \
  --output-format stream-json \
  --cwd /path/to/project \
  "<prompt>"

Key behaviors:

  1. Non-interactive mode: Uses droid exec subcommand with prompt as argument
  2. Tracing: --output-format stream-json when tracing is enabled
  3. Working directory: --cwd set to the current task workspace

Troubleshooting

"droid CLI not found"

Ensure droid is installed and in your PATH:

Bash
which droid
# Should output: /path/to/droid

"Authentication failed"

Set FACTORY_API_KEY or run droid auth.

"Tracing not showing"

  1. Ensure enableTracing = true
  2. Ensure subagentTracingDetail is not "off"
  3. Press u to show the tracing panel

Next Steps