Claude Code Agent

The Claude Code agent plugin integrates with Anthropic's claude CLI to execute AI coding tasks. It's the default agent for Ralph TUI and provides the richest feature set.

INFO

Claude Code supports subagent tracing - Ralph TUI can show nested tool calls (Read, Write, Task) in real-time as Claude works.

Prerequisites

Install Claude Code CLI:

Bash

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

Verify installation:

Bash

claude --version

Basic Usage

Run with Claude

Use the --agent claude flag (or set as default in config):

Bash

ralph-tui run --prd ./prd.json --agent claude

Select a Model

Override the model with --model:

Bash

ralph-tui run --prd ./prd.json --model opus

Enable Subagent Tracing

Press t in the TUI to cycle through tracing detail levels, or configure in config:

TOML

subagentTracingDetail = "full"

Configuration

Shorthand Config

The simplest configuration:

TOML

# .ralph-tui/config.toml
agent = "claude"
 
[agentOptions]
model = "sonnet"

Full Config

For advanced control:

TOML

[[agents]]
name = "my-claude"
plugin = "claude"
default = true
command = "claude"  # Override CLI path if needed
timeout = 300000    # 5 minute timeout
 
[agents.options]
model = "sonnet"
printMode = "text"

Options Reference

Option	Type	Default	Description
`model`	string	-	Model variant: `sonnet`, `opus`, or `haiku`
`printMode`	string	`"text"`	Output mode: `text`, `json`, or `stream`
`timeout`	number	`0`	Execution timeout in ms (0 = no timeout)
`command`	string	`"claude"`	Path to Claude CLI executable

INFO

For simple configs, you can use the top-level command option instead of the [[agents]] array:

TOML

agent = "claude"
command = "ccr code"  # Use Claude Code Router

See Custom Command for details.

Models

Claude Code supports three model variants:

Model	Description	Use Case
`sonnet`	Balanced performance and cost	Most tasks (default)
`opus`	Most capable, highest cost	Complex reasoning, architecture
`haiku`	Fastest, lowest cost	Simple tasks, rapid iteration

Select via CLI or config:

Bash

# CLI
ralph-tui run --prd ./prd.json --model opus
 
# Config
[agentOptions]
model = "opus"

Subagent Tracing

Claude Code emits structured JSONL when running with --output-format stream-json. Ralph TUI parses this to display:

Tool invocations (Read, Write, Bash, Task, etc.)
Nested subagent calls and their output
Duration and status of each operation
Token usage and cost

Tracing Levels

Level	Description
`off`	No tracing, show raw output only
`minimal`	Show start/complete events
`moderate`	Events with description and duration
`full`	Events with nested output and hierarchy

Configure in config:

TOML

subagentTracingDetail = "full"

Or toggle in TUI:

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

INFO

Subagent tracing requires Claude's streaming JSON output. Ralph TUI automatically adds the necessary flags (--verbose --output-format stream-json) when tracing is enabled.

Autonomous Operation

Ralph TUI runs Claude Code with --dangerously-skip-permissions for fully autonomous operation. This is required because ralph-tui cannot relay interactive prompts back to the agent.

INFO

Claude will execute file modifications, terminal commands, and more without asking for confirmation. Review tasks carefully before starting execution.

File Context

Claude Code supports adding directory context via --add-dir. Ralph TUI extracts directories from any file paths in your task and adds them automatically.

This helps Claude understand your project structure when working on related files.

How It Works

When Ralph TUI executes a task with Claude:

Build command: Constructs claude --print [options]
Pass prompt via stdin: Avoids shell escaping issues with special characters
Stream output: Captures stdout/stderr in real-time
Parse JSONL (if tracing enabled): Extracts structured tool call data
Detect completion: Watches for <promise>COMPLETE</promise> token
Handle exit: Reports success, failure, or timeout

CLI Arguments

Ralph TUI builds these arguments:

Bash

claude \
  --print \
  --verbose \                           # When tracing enabled
  --output-format stream-json \         # When tracing enabled
  --model sonnet \                      # If model specified
  --dangerously-skip-permissions \      # Always enabled
  --add-dir /path/to/context \          # From file context
  < prompt.txt                          # Prompt via stdin

Rate Limit Handling

Configure fallback behavior for API rate limits:

TOML

agent = "claude"
fallbackAgents = ["opencode"]
 
[rateLimitHandling]
enabled = true
maxRetries = 3
baseBackoffMs = 5000
recoverPrimaryBetweenIterations = true

When Claude hits rate limits:

Retry with exponential backoff
After maxRetries, switch to first available fallback agent
Between iterations, attempt to recover to primary agent

Troubleshooting

"Claude CLI not found"

Ensure Claude is installed and in your PATH:

Bash

which claude
# Should output: /path/to/claude
 
# If not found, install:
npm install -g @anthropic-ai/claude-code

"Execution timeout"

Increase the timeout for complex tasks:

TOML

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

"Task not completing"

Ensure your prompt template includes instructions to output the completion token:

HANDLEBARS

When finished (or if already complete), signal completion with:
<promise>COMPLETE</promise>

"Subagent tracing not showing"

Ensure subagentTracingDetail is not "off"
Press u to toggle the tracing panel visibility
Check that Claude is outputting JSONL (run manually with --verbose --output-format stream-json)

Next Steps

OpenCode Agent - Multi-provider alternative
Configuration - Full options reference
Prompt Templates - Customize task prompts