RalphTUI

Gemini Agent

Integrate Google's Gemini CLI with Ralph TUI for AI-assisted coding.

Gemini Agent

The Gemini agent plugin integrates with Google's gemini-cli CLI to execute AI coding tasks. It supports YOLO mode for autonomous operation and streaming JSONL output for subagent tracing.

INFO

Gemini supports subagent tracing via stream-json output - Ralph TUI can show tool calls in real-time as Gemini works.

Prerequisites

Install Gemini CLI:

Bash
npm install -g @google/gemini-cli

Verify installation:

Bash
gemini-cli --version

Basic Usage

Run with Gemini

Use the --agent gemini flag:

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

Select a Model

Override the model with --model:

Bash
ralph-tui run --prd ./prd.json --agent gemini --model gemini-2.5-pro

Enable YOLO Mode

Configure auto-approve in config:

TOML
[agentOptions]
yoloMode = true

Configuration

Shorthand Config

The simplest configuration:

TOML
# .ralph-tui/config.toml
agent = "gemini"
 
[agentOptions]
model = "gemini-2.5-pro"

Full Config

For advanced control:

TOML
[[agents]]
name = "my-gemini"
plugin = "gemini"
default = true
command = "gemini-cli"
timeout = 300000
 
[agents.options]
model = "gemini-2.5-pro"
yoloMode = true

Options Reference

OptionTypeDefaultDescription
modelstring-Gemini model: gemini-2.5-pro, gemini-2.5-flash
yoloModebooleantrueSkip approval prompts for autonomous operation
timeoutnumber0Execution timeout in ms (0 = no timeout)
commandstring"gemini-cli"Path to Gemini CLI executable

Models

Gemini CLI supports these model variants:

ModelDescriptionUse Case
gemini-2.5-proMost capableComplex tasks, architecture decisions
gemini-2.5-flashFast and efficientQuick tasks, rapid iteration

Select via CLI or config:

Bash
# CLI
ralph-tui run --prd ./prd.json --agent gemini --model gemini-2.5-flash
 
# Config
[agentOptions]
model = "gemini-2.5-pro"

YOLO Mode

When yoloMode is enabled (default), Gemini will skip approval prompts and auto-approve all actions. This is required for Ralph TUI's autonomous operation since it cannot relay interactive prompts.

TOML
[agentOptions]
yoloMode = true
INFO

YOLO mode is named after Gemini CLI's --yolo flag. Despite the name, it's essential for automated workflows.

Subagent Tracing

Gemini emits structured JSONL via --output-format stream-json (always enabled). Ralph TUI parses this to display:

  • Tool invocations and their output
  • Duration and status of each operation
  • Nested operations and their hierarchy

Enabling Tracing

TOML
subagentTracingDetail = "full"

Or toggle in TUI:

  • Press t to cycle through detail levels
  • Press T (Shift+T) to toggle the subagent tree panel

How It Works

When Ralph TUI executes a task with Gemini:

  1. Build command: Constructs gemini-cli [options]
  2. Pass prompt via stdin: Avoids shell escaping issues with special characters
  3. Stream output: Captures stdout/stderr in real-time
  4. Parse JSONL: Extracts structured tool call data (always enabled)
  5. Detect completion: Watches for completion token
  6. Handle exit: Reports success, failure, or timeout

CLI Arguments

Ralph TUI builds these arguments:

Bash
gemini-cli \
  --output-format stream-json \    # Always used for structured output
  -m gemini-2.5-pro \              # If model specified
  --yolo \                         # When yoloMode enabled
  < prompt.txt                     # Prompt via stdin

Model Validation

Gemini agent validates that model names start with gemini-:

TypeScript
// Valid models
"gemini-2.5-pro"
"gemini-2.5-flash"
 
// Invalid - will show error
"gpt-4"
"claude-3"

Troubleshooting

"Gemini CLI not found"

Ensure Gemini is installed and in your PATH:

Bash
which gemini-cli
# Should output: /path/to/gemini-cli
 
# If not found, install:
npm install -g @google/gemini-cli

If you still use a legacy gemini binary, Ralph TUI accepts it as a fallback alias.

"Invalid model"

Ensure your model name starts with gemini-:

TOML
[agentOptions]
model = "gemini-2.5-pro"  # Correct
# model = "gpt-4"         # Wrong - not a Gemini model

"Execution timeout"

Increase the timeout for complex tasks:

TOML
[[agents]]
name = "gemini"
plugin = "gemini"
timeout = 600000  # 10 minutes

Next Steps