Agent UI Components
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Agent UI Components within the opcode project provide a comprehensive graphical interface for managing, configuring, and executing autonomous agents powered by Claude Code. These components bridge the gap between low-level agent logic and the end-user, offering features such as an agent library, real-time execution monitoring with streaming output, and integration with remote repositories for importing pre-configured agents.
The system is designed to handle complex agent lifecycles, including creation via Markdown-based system prompts, execution within specific project directories, and session management for concurrent background runs. Users can interact with agents through a centralized management hub or specialized modals, ensuring seamless integration into the developer's workflow.
Sources: src/components/CCAgents.tsx, src/components/AgentsModal.tsx, src/components/AgentExecution.tsx
Agent Management Hub
The management hub serves as the primary entry point for agent-related operations. It allows users to browse existing agents, import new ones, and view historical execution metrics.
Key Management Features
- Agent Grid and Pagination: Displays agents in a responsive grid (3x3 layout) with support for pagination when the library grows. Sources: src/components/CCAgents.tsx:185-263
- Import/Export System: Supports importing agents from local
.opcode.jsonfiles or directly from a curated GitHub repository. Agents can also be exported for sharing. Sources: src/components/CCAgents.tsx:142-179, src/components/GitHubAgentBrowser.tsx - Execution History: Provides a list of recent and currently running agent sessions, including status indicators and performance metrics like token usage and duration. Sources: src/components/CCAgents.tsx:325-342, src/components/AgentsModal.tsx:112-119
Agent Management Flow
This diagram illustrates the lifecycle of an agent from discovery/creation to execution.
Agent Execution and Monitoring
The execution engine is responsible for triggering agent tasks and providing real-time feedback to the user. It utilizes Tauri's event system to stream data from background processes.
Execution Lifecycle
- Configuration: The user selects a model (Sonnet or Opus) and provides a task description. Sources: src/components/AgentExecution.tsx:210-230
- Initialization: The UI calls the
api.executeAgentmethod, which spawns a background process and returns a uniquerunId. Sources: src/components/AgentExecution.tsx:238-251 - Streaming: The component listens for events scoped to the
runId(e.g.,agent-output:ID,agent-error:ID) to update the UI without blocking. Sources: src/components/AgentExecution.tsx:265-300 - Completion: Final metrics such as total cost (USD), elapsed time, and token breakdown are displayed upon completion or failure. Sources: src/components/AgentExecution.tsx:640-660
Streaming Communication Sequence
The following sequence diagram shows the asynchronous communication between the UI, the Backend API, and the running Agent process.
Specialized UI Components
StreamMessage
The StreamMessage component is a sophisticated renderer for the varied output formats generated by agents. It handles text, thinking blocks, and tool-specific widgets.
| Message Type | Description | Components Used |
|---|---|---|
| System | Initialization info like Session ID and model. | SystemInitializedWidget |
| Thinking | Internal reasoning steps from the model. | ThinkingWidget |
| Tool Use | Visual representation of tool calls (Read, Write, Bash). | EditWidget, BashWidget, etc. |
| Tool Result | The output or feedback from a tool execution. | EditResultWidget, LSResultWidget |
| Result | Final summary of the task with metrics. | ReactMarkdown, SyntaxHighlighter |
Sources: src/components/StreamMessage.tsx:58-300
CreateAgent Form
A dedicated editor for configuring agent behavior. It features a Markdown editor for the system prompt, allowing developers to define complex personas and workflows (e.g., "Unit Tests Bot" or "Security Scanner").
- System Prompt: Defines the core identity and rules of the agent using Markdown. Sources: src/components/CreateAgent.tsx:232-243
- Icon Picker: Allows selection from a library of semantic icons (bot, shield, code, etc.). Sources: src/components/CreateAgent.tsx:180-198
- Model Defaults: Sets the default model family for the agent, typically
sonnetfor efficiency oropusfor complex reasoning. Sources: src/components/CreateAgent.tsx:201-240
Technical Implementation Details
Data Structures
The following structures are used to represent agents and their execution state:
// From src/lib/api.ts (referenced in components)
export interface Agent {
id?: number;
name: string;
icon: string;
system_prompt: string;
default_task?: string;
model: string;
created_at: string;
}
export interface ClaudeStreamMessage {
type: "system" | "assistant" | "user" | "result";
subtype?: string;
message?: {
content?: any[];
usage?: { input_tokens: number; output_tokens: number; };
};
}
Sources: src/components/AgentExecution.tsx:59-75, src/components/CCAgents.tsx:100-110
Component Layout Architecture
This diagram shows the relationship between the main agent components.
Conclusion
The Agent UI Components provide a robust and extensible framework for interacting with Claude Code agents. By leveraging a real-time event-driven architecture and specialized rendering widgets, the system maintains high responsiveness and clarity even during complex, long-running background tasks. The integration of local and remote agent libraries ensures that users can easily expand their toolkit with purpose-built AI assistants.
Sources: src/components/AgentExecution.tsx, src/components/CCAgents.tsx