Session Interface Components
Relevant source files
The following files were used as context for generating this wiki page:
The Session Interface Components form the core interactive environment for Opcode, enabling users to communicate with Claude Code, manage project-specific workflows, and visualize real-time tool execution. These components are designed to work across both Tauri desktop environments and web-based server modes, providing a unified UI for streaming AI responses and terminal-like interactions.
This module handles complex state management for message streaming, prompt queuing, and session persistence. It integrates specialized widgets for displaying terminal output, file edits, and MCP (Model Context Protocol) tool results, ensuring that raw JSONL data from the Claude binary is rendered into a human-readable, actionable interface.
Sources: src/components/ClaudeCodeSession.tsx:1-125, web_server.design.md:5-20
Core Component Architecture
The session interface is built around the ClaudeCodeSession component, which serves as the primary orchestrator. It manages the lifecycle of a session, from initialization and path selection to real-time message processing and session cancellation.
ClaudeCodeSession Orchestrator
This component maintains the internal state for messages, loading indicators, and token usage. It utilizes a custom listen implementation that detects whether the app is running in a Tauri environment or a standard web browser, dispatching DOM events accordingly to maintain feature parity.
The flow demonstrates how user input is routed through the API adapter based on the environment to reach the Claude binary, with output returning via event listeners for real-time UI updates.
Sources: src/components/ClaudeCodeSession.tsx:28-60, web_server.design.md:40-55
Component Breakdown
| Component | Responsibility | Key Properties |
|---|---|---|
ClaudeCodeSession | Main session container and state manager. | session, initialProjectPath, onStreamingChange |
FloatingPromptInput | User input bar with model selection and command support. | onSend, onCancel, isLoading |
StreamMessage | Specialized renderer for different message types (text, tool, result). | message, streamMessages, onLinkDetected |
MessageList | Virtualized list for efficient rendering of long chat histories. | messages, isStreaming, projectPath |
TimelineNavigator | Visual interface for session checkpoints and branching. | sessionId, onCheckpointSelect, onFork |
Sources: src/components/ClaudeCodeSession.tsx:75-120, src/components/claude-code-session/MessageList.tsx
Message Processing and Rendering
The interface processes a stream of ClaudeStreamMessage objects. These messages are categorized into types such as assistant, user, system, and result.
StreamMessage Rendering Logic
The StreamMessage component acts as a factory, selecting the appropriate widget based on the tool being executed by Claude. It handles both successful outputs and error states (stderr).
- Assistant Messages: Render markdown text, thinking blocks, and tool invocation widgets (e.g.,
BashWidget,EditWidget,MCPWidget). - User Messages: Display user prompts and the results of tool executions returned to the AI.
- System Messages: Handle initialization (
init), status updates, and errors.
Sources: src/components/StreamMessage.tsx:50-180
Tool Execution Flow
When Claude invokes a tool, the interface tracks the execution from "tool_use" in an assistant message to "tool_result" in a subsequent user message.
The sequence shows the transition of a tool widget from a pending state to a completed result state based on streaming events.
Sources: src/components/StreamMessage.tsx:80-120, web_server.design.md:58-75
Session Management and Persistence
Opcode implements session persistence through SessionPersistenceService, allowing users to resume previous interactions.
Prompt Queuing
To prevent race conditions during streaming, the interface implements a prompt queue. If a user submits a prompt while the assistant is already generating, the message is stored in queuedPrompts and automatically dispatched once the current process completes.
Sources: src/components/ClaudeCodeSession.tsx:160-175, src/components/ClaudeCodeSession.refactored.tsx:105-125
Checkpoints and Forking
Users can create manual or automatic checkpoints within a session. The TimelineNavigator allows for:
- Restoring: Jumping back to a previous state in the session history.
- Forking: Creating a new session branch from a specific checkpoint to explore alternative coding paths.
Sources: src/components/ClaudeCodeSession.tsx:780-820, src/components/ClaudeCodeSession.refactored.tsx:210-230
Event Handling Implementation
The interface uses a dynamic listen function to bridge Tauri's event system with standard DOM events for web compatibility.
// src/components/ClaudeCodeSession.tsx:43-52
const webListen = (eventName: string, callback: (event: { payload: unknown }) => void): Promise<UnlistenFn> => {
const domEventHandler = (event: Event) => {
const customEvent = event as CustomEvent;
callback({ payload: customEvent.detail });
};
window.addEventListener(eventName, domEventHandler);
return Promise.resolve(() => window.removeEventListener(eventName, domEventHandler));
};
Sources: src/components/ClaudeCodeSession.tsx:43-52
Summary of Technical Specifications
Data Structures
| Field | Type | Description |
|---|---|---|
ClaudeStreamMessage | Object | The fundamental unit of the stream, containing type, content, and metadata. |
Session | Object | Represents a persisted session with id, project_id, and project_path. |
ClaudeMdFile | Object | Metadata for CLAUDE.md files including absolute_path and relative_path. |
Sources: src/components/ClaudeCodeSession.tsx:75-90, src/components/SessionList.tsx:15-30
Critical Logic: Session Reconnection
When a user reopens a project, the checkForActiveSession function queries the backend for running Claude processes. If a process matching the session ID is found, the UI calls reconnectToSession, attaching new listeners to the existing stream to prevent data loss.
Sources: src/components/ClaudeCodeSession.tsx:325-360
The Session Interface Components successfully provide a high-fidelity GUI for Claude Code, abstracting the complexities of process streaming, tool rendering, and session branching into a cohesive developer experience.