Extension Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The QQCode VSCode extension serves as a bridge between the Visual Studio Code IDE and the QQCode CLI coding assistant. Its primary purpose is to provide a rich, interactive chat interface within the IDE while delegating complex agentic tasks—such as file manipulation, shell command execution, and LLM orchestration—to a local subprocess running the QQCode Python package.
The architecture is built on a decoupled model where the extension handles UI rendering (Webview), state persistence (WorkspaceState), and message passing, while a backend wrapper manages the lifecycle of the CLI tool and parses its line-delimited JSON stream into UI events.
Sources: vscode-extension/README.md:85-88, vscode-extension/src/chatView/ChatViewProvider.ts:40-45
Core Components
The extension is structured into three primary layers: the Webview UI, the Extension Host logic, and the Backend CLI wrapper.
ChatViewProvider
The ChatViewProvider implements the vscode.WebviewViewProvider interface to manage the chat panel. It is responsible for initializing the webview, handling bidirectional communication using VS Code's postMessage API, and maintaining the session's state.
Sources: vscode-extension/src/chatView/ChatViewProvider.ts:51-85
QQCodeBackend
This component manages the interaction with the qqcode CLI. It spawns the CLI as a child process using spawn and communicates via stdin (for approvals) and stdout (for streaming responses). It uses the --output vscode flag to receive structured JSON events from the CLI.
Sources: vscode-extension/src/qqcodeBackend.ts:15-30, vscode-extension/src/qqcodeBackend.ts:168-185
Protocol and Messaging
Communication between the extension and the webview is strictly typed through a defined protocol. This ensures that actions like user messages, tool calls, and plan approvals are handled consistently across the boundary.
Sources: vscode-extension/src/chatView/protocol/messages.ts:10-25
| Component | Responsibility | Relevant Files |
|---|---|---|
| Webview (JS/CSS/HTML) | Renders chat bubbles, tool approval UI, and manages user input. | chat.js, styles.css, index.html |
| ChatViewProvider | Coordinates between UI and Backend; manages VS Code workspace state. | ChatViewProvider.ts |
| QQCodeBackend | CLI process management, JSON parsing, and stdout/stderr handling. | qqcodeBackend.ts |
| Protocol | Defines TypeScript types for inter-process communication. | messages.ts |
| Sources: vscode-extension/README.md:100-110, vscode-extension/package.json:75-100 |
Data Flow and Interaction
The system operates primarily on an asynchronous event-driven loop. When a user sends a message, it travels from the webview to the extension host, which then triggers the CLI.
Message Streaming Sequence
The following diagram illustrates the flow of a single user prompt resulting in a tool execution and a final response.
The extension captures the CLI's stdout using readline.createInterface to process each line as an independent JSON event.
Sources: vscode-extension/src/qqcodeBackend.ts:250-275, vscode-extension/media/webview/chat.js:190-210
Execution Modes and Approvals
QQCode supports different execution modes that control how tools are authorized. The architecture provides specific UI flows for "Plan" mode and tool-level approvals.
Mode Selection
Users can toggle between three modes, which are passed to the CLI via the --mode flag:
- Plan: The agent generates a plan first, requiring a
plan_approval_requiredevent before execution. - Interactive: The agent proceeds but requires
tool.approval_requiredfor individual tool calls. - Auto-Approve: The agent executes tools without interruption.
Sources: vscode-extension/src/chatView/protocol/messages.ts:10, vscode-extension/src/qqcodeBackend.ts:161-165
Approval Mechanism
When the CLI requires approval, the process pauses and waits for input on stdin. The extension's backend wrapper provides dedicated methods to write these responses back to the process.
Extension Manifest and Configuration
The extension is configured through standard VS Code settings, allowing users to point to custom CLI installations.
Key Commands and Settings
| Setting/Command | Description | Default |
|---|---|---|
qqcode.commandPath | Path to the CLI executable (supports uv run qqcode). | "qqcode" |
qqcode.autoApprove | Global toggle for automatic tool execution. | false |
qqcode.defaultMode | Default mode for new conversations. | "plan" |
qqcode.openChat | Command to focus the QQCode Chat webview. | N/A |
| Sources: vscode-extension/package.json:115-145 |
Context Integration
The extension enhances the prompt by providing "Active File" and "Selected Code" context. Before streaming a prompt, the backend generates a temporary Markdown file containing the current editor state and passes its path to the CLI via the QQCODE_VSCODE_CONTEXT environment variable.
Sources: vscode-extension/src/qqcodeBackend.ts:335-360
Summary
The QQCode Extension Architecture follows a sidecar-like pattern where the VS Code extension acts as a thin, reactive UI layer for a powerful CLI-based agent. By leveraging line-delimited JSON over standard streams (stdio), it achieves real-time streaming and interactive tool orchestration while maintaining high performance and decoupling from the Python runtime.
Sources: vscode-extension/README.md:85-95, vscode-extension/src/qqcodeBackend.ts:200-210