UI Widgets library
Relevant source files
The following files were used as context for generating this wiki page:
The UI Widgets library is a specialized collection of React components designed to provide rich, interactive visual representations for Claude Code tool executions and system events. Instead of displaying raw JSON or text output, these widgets parse tool inputs and results to render formatted UI elements like file trees, diff viewers, task progress indicators, and interactive todo lists.
This library serves as the presentation layer for the agent execution stream, bridging the gap between CLI-style operations and a modern graphical interface. It supports a wide range of functionalities including file system operations, search tools, Model Context Protocol (MCP) integrations, and sub-agent task management.
Sources: src/components/ToolWidgets.tsx, src/components/StreamMessage.tsx:1-50, README.md
Core Architecture
The widget system operates within a streaming message architecture where incoming Claude messages are intercepted and mapped to specific visual components based on the tool_use name or message subtype.
Data Flow and Rendering Logic
The StreamMessage component acts as the primary orchestrator, determining which widget to instantiate by analyzing the ClaudeStreamMessage object. It maintains a mapping of tool call IDs to their respective results to ensure widgets can display both the initial tool call and its eventual output.
The system uses a stateful map (toolResults) to track results by tool_use_id, allowing widgets to transition from a "Loading/Running" state to a "Complete" state.
Sources: src/components/StreamMessage.tsx:55-100, web_server.design.md
Specialized Tool Widgets
File System and Editing Widgets
These widgets handle operations related to file manipulation, directory exploration, and code changes.
| Widget | Purpose | Key Features |
|---|---|---|
LSResultWidget | Displays directory structures. | Recursive tree view, file-type icons, collapsible folders. |
ReadResultWidget | Shows file contents. | Syntax highlighting, line numbers, "Expand/Collapse" for large files. |
EditWidget | Previews code edits. | Line-by-line diff view using diff library, syntax highlighting. |
WriteWidget | Shows file creation/overwrite. | Maximized code modal view, syntax highlighting. |
Sources: src/components/ToolWidgets.tsx:150-450, src/components/ToolWidgets.tsx:714-800
Search and Analysis Widgets
These components provide visual feedback for pattern matching and information retrieval.
GrepWidget: Displays search patterns with regex highlighting and a list of matches including file paths and line numbers.WebSearchWidget: Renders web search results as interactive cards or pills, supporting external link opening via Tauri shell.WebFetchWidget: Shows URL fetching status and a truncated preview of the fetched content with an option to view the full text.
Sources: src/components/ToolWidgets.tsx:555-700, src/components/ToolWidgets.tsx:1285-1450
Task and Agent Management
Widgets that facilitate the management of sub-tasks and the initialization of the agent environment.
*TaskWidget**: Used when an agent spawns a sub-task. It displays the task description and instructions in a dedicated purple-themed card.
SystemInitializedWidget: Provides a summary of the environment, including Session ID, working directory, and a categorized list of available regular and MCP tools.
Sources: src/components/ToolWidgets.tsx:1093-1130, src/components/ToolWidgets.tsx:1240-1280
Model Context Protocol (MCP) Integration
The MCPWidget is a dynamic component designed to handle any tool following the MCP standard. It uses a specific naming convention (mcp__namespace__method) to identify and format external tool calls.
MCP Tool Formatting Logic
- Namespace Parsing: Extracts the provider from the tool name string.
- Method Formatting: Converts snake_case or kebab-case methods into readable titles.
- Parameter Display: Uses
react-syntax-highlighterto render JSON input parameters with a token count estimation.
Sources: src/components/ToolWidgets.tsx:848-935
Task and Todo Tracking
The library includes advanced widgets for project management within the chat interface, specifically through TodoWidget and TodoReadWidget.
TodoReadWidget Features
- Multiple Views: Supports List, Board (Kanban), Timeline (dependency-based), and Stats (progress bars).
- Exporting: Allows downloading the current todo state as JSON or Markdown.
- Filtering: Real-time search and status-based filtering (Pending, In Progress, Completed, Cancelled).
Sources: src/components/ToolWidgets.tsx:1550-1800
Implementation Details
Syntax Highlighting
The library relies on react-syntax-highlighter and a custom getClaudeSyntaxTheme to provide consistent code aesthetics. It supports a mapping of over 30 file extensions to their respective languages, including TypeScript, Rust, Python, and SQL.
Sources: src/components/ToolWidgets.tsx:288-330, src/components/ToolWidgets.tsx:702-712
MultiEdit Logic
The MultiEditWidget handles complex scenarios where multiple changes are applied to a single file. It calculates diffs for each individual edit block and provides a collapsible interface to review them before or after application.
Sources: src/components/ToolWidgets.tsx:1003-1090
Summary
The UI Widgets library is central to the "Opcode" experience, transforming raw agent logs into a structured IDE-like interface. By providing specialized views for everything from file diffs to project statistics, it enables developers to monitor and interact with autonomous agents effectively.
Sources: README.md, web_server.design.md