Relevant source files

The following files were used as context for generating this wiki page: - [vibe/cli/textual_ui/widgets/tool_widgets.py](https://github.com/RemyLoveLogicAI/qqcode/blob/main/vibe/cli/textual_ui/widgets/tool_widgets.py) - [vscode-extension/src/chatView/ChatViewProvider.ts](https://github.com/RemyLoveLogicAI/qqcode/blob/main/vscode-extension/src/chatView/ChatViewProvider.ts) - [vscode-extension/media/webview/chat.js](https://github.com/RemyLoveLogicAI/qqcode/blob/main/vscode-extension/media/webview/chat.js) - [vscode-extension/media/webview/index.html](https://github.com/RemyLoveLogicAI/qqcode/blob/main/vscode-extension/media/webview/index.html) - [vscode-extension/media/webview/styles.css](https://github.com/RemyLoveLogicAI/qqcode/blob/main/vscode-extension/media/webview/styles.css) - [vibe/cli/entrypoint.py](https://github.com/RemyLoveLogicAI/qqcode/blob/main/vibe/cli/entrypoint.py)

# Chat Interface & Widgets The Chat Interface and its associated widgets represent the primary interaction layer for the QQCode assistant. This system is implemented through two distinct paradigms: a Textual-based Terminal User Interface (TUI) for CLI users and a Webview-based interface for the VS Code extension. The interface facilitates real-time communication between the user and the AI agent, providing structured displays for messages, tool executions, and planning phases. Sources: [vibe/cli/entrypoint.py:307-317](), [vscode-extension/src/chatView/ChatViewProvider.ts:34-40]() ## Architecture Overview The interface follows a provider-consumer model. In the VS Code environment, the `ChatViewProvider` manages the lifecycle of the webview, handling message passing between the VS Code extension host and the frontend assets (HTML/JS/CSS). In the CLI environment, the interface is managed through the Textual framework, utilizing specialized widgets to render complex data like diffs and tool results. ```mermaid flowchart TD subgraph VS_Code_Extension A[ChatViewProvider.ts] -->|postMessage| B[chat.js] B -->|onDidReceiveMessage| A B --> C[index.html] B --> D[styles.css] end subgraph CLI_TUI E[entrypoint.py] --> F[run_textual_ui] F --> G[tool_widgets.py] end H[QQCode Backend] <--> A H <--> F ``` The diagram shows the dual-path architecture supporting both VS Code and CLI interfaces. Sources: [vscode-extension/src/chatView/ChatViewProvider.ts:88-115](), [vibe/cli/entrypoint.py:307-317]() ## VS Code Chat Interface Components The VS Code extension utilizes a webview to render a modern chat experience. It is composed of several interactive regions and state-managed components. ### 1. View Provider & State Management `ChatViewProvider` maintains the `ChatState`, which tracks the current session, message history, selected model, and execution mode. It persists this state using `workspaceState` and `globalState`. Sources: [vscode-extension/src/chatView/ChatViewProvider.ts:16-32](), [vscode-extension/src/chatView/ChatViewProvider.ts:69-100]() ### 2. User Input & Autocompletion The input area features a dynamic textarea with `@` mention support for file paths. The `PathCompleter` and `FileIndexer` provide suggestions that are rendered in a popup within the webview. | Component | Logic Source | UI Implementation | | :--- | :--- | :--- | | **Input Box** | `chat.js` | `textarea#user-input` | | **Autocompletion** | `PathCompleter.ts` | `.completion-popup` | | **Mode Selector** | `ChatViewProvider.ts` | `select#mode-selector` | Sources: [vscode-extension/media/webview/chat.js:770-800](), [vscode-extension/media/webview/index.html:43-51](), [vscode-extension/src/chatView/ChatViewProvider.ts:153-186]() ### 3. Execution Modes The interface supports three distinct execution modes that dictate how the agent interacts with tools. * **Plan Mode:** AI generates a plan; changes are blocked. Requires user approval to proceed to implementation. * **Interactive Mode:** Standard conversational mode where tool calls require manual user approval. * **Auto-Approve Mode:** Tools execute without pausing for user confirmation. Sources: [vscode-extension/media/webview/chat.js:930-945](), [vscode-extension/src/chatView/ChatViewProvider.ts:515-525]() ## TUI Tool Widgets In the CLI interface, specialized Python classes inherit from Textual's `Vertical` or `Static` widgets to render tool-specific information. ### Tool Approval and Result Handling Each core tool has a corresponding "Approval" widget (shown before execution) and a "Result" widget (shown after execution). ```mermaid classDiagram class ToolApprovalWidget { +dict data +compose() Result } class ToolResultWidget { +dict data +bool collapsed +compose() Result } ToolApprovalWidget <|-- BashApprovalWidget ToolApprovalWidget <|-- WriteFileApprovalWidget ToolApprovalWidget <|-- EditApprovalWidget ToolResultWidget <|-- BashResultWidget ToolResultWidget <|-- EditResultWidget ``` The hierarchy demonstrates the specialization of UI components for different tool types. Sources: [vibe/cli/textual_ui/widgets/tool_widgets.py:9-30]() ### Specialized Rendering Logic * **EditApprovalWidget:** Renders Git-style diffs with specific CSS classes for added (`+`) and removed (`-`) lines. * **WriteFileResultWidget:** Truncates long file content to a maximum of 10 lines by default to maintain UI readability. * **TodoResultWidget:** Displays a task list with status icons (e.g., `☐` for pending, `☑` for completed). Sources: [vibe/cli/textual_ui/widgets/tool_widgets.py:102-125](), [vibe/cli/textual_ui/widgets/tool_widgets.py:73-99](), [vibe/cli/textual_ui/widgets/tool_widgets.py:155-180]() ## Webview Communication Flow Communication between the extension host and the chat webview is handled via a JSON protocol. The `ChatViewProvider` listens for webview messages and routes them to the `QQCodeBackend`. ```mermaid sequenceDiagram participant Webview as "Webview (chat.js)" participant Provider as "ChatViewProvider" participant Backend as "QQCodeBackend" Webview->>Provider: {type: 'userMessage', text: '...'} Provider->>Backend: streamPrompt(processedText) Backend-->>Provider: chunk (text/tool_call) Provider-->>Webview: {type: 'updateAssistantMessage', content: '...'} Note over Webview, Backend: Tool Approval Flow Backend-->>Provider: kind: 'tool_approval_required' Provider-->>Webview: {type: 'toolApprovalRequired', ...} Webview->>Provider: {type: 'approveToolCall', approved: true} Provider->>Backend: sendApprovalResponse(id, true) ``` This flow illustrates the asynchronous, event-driven nature of the chat interface. Sources: [vscode-extension/src/chatView/ChatViewProvider.ts:240-340](), [vscode-extension/media/webview/chat.js:145-215]() ## Conclusion The "Chat Interface & Widgets" system provides a robust framework for agent-human collaboration. By utilizing specialized widgets for tools and a structured communication protocol for the VS Code webview, the system ensures that complex technical operations—such as file edits, shell commands, and multi-step plans—are presented clearly and safely to the developer.