Crate ralph_adapters

Expand description

§ralph-adapters

Agent adapters for the Ralph Orchestrator framework.

This crate provides implementations for various AI agent backends:

Claude (Anthropic)
Gemini (Google)
Codex (OpenAI)
Pi (pi-coding-agent)
Roo (Roo Code)
Amp
Custom commands

Each adapter implements the common CLI executor interface.

§Auto-Detection

When config specifies agent: auto, the auto_detect module handles detecting which backends are available in the system PATH.

§PTY Mode

The pty_executor module provides PTY-based execution for Claude CLI, preserving rich terminal UI features (colors, spinners, animations) while allowing Ralph to orchestrate iterations. Supports interactive mode (user input forwarded) and observe mode (output-only).

Re-exports§

pub use pty_handle::ControlCommand;
pub use pty_handle::PtyHandle;

Modules§

pty_handle: PTY handle abstraction for TUI integration.

Structs§

AcpExecutor: Executor for ACP-based backends (kiro-acp).
AssistantMessage: Message content from Claude’s assistant responses.
ClaudeStreamParser: Parses NDJSON lines from Claude’s stream output.
CliBackend: A CLI backend configuration for executing prompts.
CliExecutor: Executor for running prompts through CLI backends.
ConsoleStreamHandler: Writes streaming output to stdout/stderr.
CopilotAssistantMessage: Assistant message payload emitted by Copilot.
CopilotStreamParser: Parses JSONL lines from Copilot’s prompt-mode output.
CtrlCState: State machine for double Ctrl+C detection.
CustomBackendError: Error when creating a custom backend without a command.
ExecutionResult: Result of a CLI execution.
JsonRpcStreamHandler: Stream handler that emits JSON-RPC events to a writer.
NoBackendError: Error returned when no backends are available.
PiCost: Cost breakdown from pi.
PiSessionState: State accumulated across events for session summary.
PiStreamParser: Parses NDJSON lines from pi’s stream output.
PiToolResult: Tool execution result.
PiTurnMessage: Message in turn_end — contains usage data.
PiUsage: Token usage statistics from pi.
PrettyStreamHandler: Renders streaming output with colors and markdown.
PtyConfig: Configuration for PTY execution.
PtyExecutionResult: Result of a PTY execution.
PtyExecutor: Executor for running prompts in a pseudo-terminal.
QuietStreamHandler: Suppresses all streaming output (for CI/silent mode).
SessionResult: Session completion result data.
TuiStreamHandler: Renders streaming output as ratatui Lines for TUI display.
Usage: Token usage statistics.
UserMessage: Message content from tool results (user turn).

Enums§

ClaudeStreamEvent: Events emitted by Claude’s --output-format stream-json.
ContentBlock: Content blocks in assistant messages.
CopilotStreamEvent: Events emitted by Copilot’s --output-format json.
CtrlCAction: Action to take after handling Ctrl+C.
OutputFormat: Output format supported by a CLI backend.
PiAssistantEvent: Assistant message event within a message_update.
PiContentBlock: Content block within a tool result.
PiStreamEvent: Events from pi’s --mode json NDJSON output.
PromptMode: How to pass prompts to the CLI tool.
TerminationType: How the PTY process was terminated.
UserContentBlock: Content blocks in user messages (tool results).

Constants§

DEFAULT_PRIORITY: Default priority order for backend detection.

Traits§

StreamHandler: Handler for streaming output events from Claude.

Functions§

detect_backend: Detects the first available backend from a priority list.
detect_backend_default: Detects a backend using default priority and all adapters enabled.
dispatch_pi_stream_event: Dispatch a pi stream event to the StreamHandler.
is_backend_available: Checks if a backend is available by running its version command.
stdout_json_rpc_handler: Creates a JsonRpcStreamHandler writing to stdout.