ralph-tui

Orchestrates iterative AI agent workflows through a terminal-based interface, managing the execution loop where agents receive tasks, call tools, process results, and decide next steps. The TUI provides real-time visualization of agent state transitions, tool invocations, and reasoning chains as they execute, with structured input/output handling for each loop iteration.

Manages tool/function definitions through a schema registry that agents can query and invoke, supporting structured function calling with parameter validation and result handling. The system translates between agent decisions (which tool to call with what parameters) and actual function execution, handling serialization of complex types and error propagation back to the agent.

Implements a state machine that tracks agent execution states (idle, thinking, tool-calling, processing-results, deciding-next-step) and manages transitions based on LLM outputs and tool results. The system handles branching logic where agents can decide to continue the loop, call additional tools, or terminate based on task completion criteria.

Renders agent execution state, tool calls, results, and reasoning chains in a terminal UI with live updates as the agent loop progresses. The TUI displays the current agent state, pending tool calls, recent results, and the reasoning trace in a structured, scrollable format with syntax highlighting for code and JSON.

Abstracts the LLM provider interface so agents can use different LLM backends (OpenAI, Anthropic, local models, etc.) without changing agent logic. The system handles provider-specific API differences, prompt formatting, response parsing, and token counting, translating between a unified agent interface and provider-specific APIs.

Constructs agent prompts with structured sections for task definition, tool availability, execution history, and decision instructions, ensuring the LLM has all necessary context to make informed decisions. The system manages prompt composition, context window optimization, and formatting to maximize LLM reasoning quality while staying within token limits.

Maintains a rolling buffer of agent execution history including previous tool calls, results, and reasoning steps, making this context available to the LLM for subsequent decisions. The system manages context window constraints by selectively including relevant history while dropping older or less relevant steps to stay within token limits.

Catches and handles errors from tool execution, LLM API failures, and invalid agent decisions, feeding error information back to the agent for recovery attempts. The system distinguishes between recoverable errors (retry with different parameters) and terminal errors (stop execution), and provides the agent with error context to inform next steps.

Monitors agent execution for signals indicating task completion (explicit stop decision, max iterations reached, timeout exceeded, or success criteria met) and gracefully terminates the agent loop. The system collects final results and execution summary for reporting.