VSCode Chat Protocol
Relevant source files
The following files were used as context for generating this wiki page:
The VSCode Chat Protocol defines the communication layer between the QQCode VSCode extension host and its associated Webview-based chat interface. It enables real-time AI assistance, streaming responses, and agentic tool execution directly within the IDE environment.
This protocol facilitates high-level interactions such as session management, model selection, execution mode switching (Plan, Interactive, Auto-Approve), and advanced context handling through file mentions. It bridges the gap between the VSCode Extension Host and the underlying QQCode CLI backend by transforming line-delimited JSON events into a structured UI experience.
Communication Architecture
The system uses a bidirectional messaging bridge. The Extension Host acts as a proxy between the QQCode CLI (backend) and the Webview (UI).
The diagram shows the flow of a user request from the UI through processing in the extension to execution in the CLI.
Sources: vscode-extension/src/chatView/ChatViewProvider.ts:317-430, vscode-extension/media/webview/chat.js:154-165, vscode-extension/src/qqcodeBackend.ts:167-185
Protocol Message Types
Webview to Extension (User Actions)
The Webview sends requests to the Extension Host to trigger backend operations or workspace changes.
| Message Type | Parameters | Description |
|---|---|---|
userMessage | text | Submits a user prompt for processing. |
selectModel | modelAlias | Switches the active AI model. |
selectMode | mode | Changes execution mode (e.g., plan, interactive). |
approveToolCall | toolCallId, approved | Responds to a tool execution request. |
openFile | path | Requests VSCode to open a specific file from the workspace. |
requestFileCompletions | text, cursorPosition | Requests path suggestions for @ mentions. |
Sources: vscode-extension/media/webview/chat.js:192-237, vscode-extension/src/chatView/ChatViewProvider.ts:145-200
Extension to Webview (UI Updates)
The Extension Host pushes state updates and streaming content to the Webview.
| Message Type | Parameters | Description |
|---|---|---|
addMessage | role, content, isHistory | Appends a message bubble to the chat container. |
toolCall | toolName, toolCallId, args | Displays an active tool execution. |
toolApprovalRequired | toolName, toolCallId, args | Renders a UI block requiring user consent. |
planApprovalRequired | plan | Shows a full implementation plan for review. |
thinkingUpdate | content | Streams the AI's internal reasoning process. |
setLoading | loading | Controls the spinner/loading state of the input area. |
Sources: vscode-extension/src/chatView/ChatViewProvider.ts:340-420, vscode-extension/media/webview/chat.js:241-285
Message Processing and Context Embedding
Before a user message is sent to the backend, it undergoes transformation to include IDE context. The extension identifies @ symbols followed by paths and embeds the file contents directly into the prompt.
Context Resolution Logic
- Anchor Detection: Identifies
@characters not preceded by alphanumeric characters. - Path Extraction: Supports quoted and unquoted path candidates.
- File Resolution: Resolves paths relative to the workspace root.
- Content Embedding: Reads file content (up to 256KB) and wraps it in markdown code blocks.
The flow describes how the extension extracts file context from mentions to enrich the prompt sent to the LLM.
Sources: vscode-extension/src/chatView/messageProcessor.ts:35-75, vscode-extension/src/chatView/messageProcessor.ts:160-195
Tool Execution Flow
QQCode uses an agentic model where the AI can request tool execution (e.g., read_file, bash). The protocol handles these via a stateful approval cycle.
Tool States
- Execution: Triggered by
toolCall, UI shows a spinning icon. - Approval: Triggered by
tool_approval_required, UI renders "Approve" and "Reject" buttons. - Result: Triggered by
tool_result, transforms the tool block into a success or error state.
This sequence illustrates the interaction required for tools that need user authorization.
Sources: vscode-extension/src/qqcodeBackend.ts:250-280, vscode-extension/media/webview/chat.js:526-570, vscode-extension/src/chatView/ChatViewProvider.ts:375-395
Session and State Persistence
The extension maintains session state to ensure conversation continuity across VSCode restarts.
- Workspace State: Stores
currentSessionIdandmessageHistoryinworkspaceState. - Global State: Stores
selectedModelandselectedModeinglobalState. - Historical Sync: When a session is resumed, the extension loads historical messages and previous tool calls, rendering them as
historicalToolCallitems in the UI.
Sources: vscode-extension/src/chatView/ChatViewProvider.ts:77-105, vscode-extension/src/chatView/ChatViewProvider.ts:476-538
Conclusion
The VSCode Chat Protocol provides a robust framework for integrating agentic AI capabilities into the developer workflow. By combining streaming JSON events with IDE-specific context processing and a stateful approval UI, it ensures that AI interactions are both powerful and transparent. The separation of concerns between the extension host (orchestration) and the webview (presentation) allows for a responsive and theme-aware user experience.