Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
QQcode is an open-source CLI coding assistant designed to provide a conversational interface for codebase exploration, modification, and interaction. The system is built on a modular architecture that separates the core agent logic, multi-provider LLM integration, and various user interfaces, including a Textual-based TUI and a VS Code extension.
The architecture emphasizes "Project-Aware Context," where the system automatically gathers directory structures, git status, and project documentation to ground the LLM's responses. It employs a "Tool System" that allows the agent to execute shell commands, read/write files, and manage tasks through a structured approval workflow.
Sources: CLAUDE.md:5-9, vibe/core/system_prompt.py:236-258
Core System Components
The project is structured into several distinct layers, each handling specific responsibilities from configuration to user interaction.
Component Breakdown
| Component | Responsibility | Key Files |
|---|---|---|
| Agent Core | Orchestrates conversation flow, tool execution, and LLM streaming. | vibe/core/agent.py |
| Tool System | Provides a framework for built-in and MCP-based tools. | vibe/core/tools/ |
| Context Engine | Generates system prompts with file trees and git metadata. | vibe/core/system_prompt.py |
| CLI & TUI | Handles terminal user interface and command-line arguments. | vibe/cli/ |
| Extension | Bridges the VS Code IDE with the QQcode CLI backend. | vscode-extension/ |
Sources: CLAUDE.md:27-55
High-Level Architecture Flow
This diagram illustrates how a user request flows through the system, from the interface to the LLM and back through tool execution.
The Agent acts as the central orchestrator, managing the lifecycle of a request, including the integration of "Skills" discovered from project-local or global directories.
Sources: CLAUDE.md:50-52, vibe/core/skills/manager.py:46-56
Context and Prompt Engineering
The ProjectContextProvider is responsible for building a comprehensive view of the current working environment. It scans the filesystem, respects .gitignore patterns, and gathers git metadata to populate the system prompt.
Context Generation Logic
- Directory Structure: Recursively builds a tree view of the project, limited by
max_depthandmax_filesconfiguration. - Git Status: Executes git commands to retrieve the current branch, main branch, and recent commit history.
- Project Docs: Automatically loads files like
AGENTS.mdorREADME.mdto provide high-level project guidance.
Sources: vibe/core/system_prompt.py:48-60, vibe/core/system_prompt.py:161-175, vibe/core/config.py:61
Tool System and Approval Workflow
Tools in QQcode are structured classes derived from BaseTool. They follow a specific execution lifecycle that includes validation and, depending on the "Execution Mode," user approval.
Execution Modes
- Plan Mode: The agent uses read-only tools to analyze the codebase and must submit a plan before making changes.
- Interactive Mode: Every tool execution requires manual user approval.
- Auto-Approve Mode: Tools are executed automatically without interruption.
Sources: vibe/cli/entrypoint.py:38-46, vscode-extension/src/chatView/ChatViewProvider.ts:18-20
Tool Call Sequence
UI components for tool results are specialized, such as the BashResultWidget or EditResultWidget, which provide syntax-highlighted diffs and command outputs.
Sources: vibe/cli/textual_ui/widgets/tool_widgets.py:63-80, vibe/cli/textual_ui/widgets/tool_widgets.py:133-145
VS Code Extension Integration
The VS Code extension serves as a wrapper around the QQcode CLI. It manages a QQCodeBackend process that communicates via structured streaming events.
Communication Protocol
The extension uses the --output vscode flag to receive structured JSON events from the CLI, which are then rendered in a Webview-based chat interface.
| Message Type | Description |
|---|---|
tool_approval_required | Triggers a UI prompt for tool execution. |
plan_approval_required | Notifies the user that a multi-step plan is ready for review. |
thinking | Streams the internal reasoning process of models (like Claude 3.7). |
text | Standard incremental response text. |
Sources: vscode-extension/src/chatView/ChatViewProvider.ts:285-350, vibe/cli/entrypoint.py:82-87
Configuration Management
QQcode uses a hierarchical configuration system based on Pydantic and TOML. It looks for config.toml in the local .qqcode/ directory before falling back to the global ~/.qqcode/ directory.
Configuration Hierarchy
- Environment Variables: Prefixed with
QQCODE_. - Local Project Config:
./.qqcode/config.toml. - Global Config:
~/.qqcode/config.toml. - Agent Overrides: Specialized TOML files in
~/.qqcode/agents/.
Sources: vibe/core/config.py:32-48, vibe/core/config.py:392-402
Summary
The QQcode architecture is designed for extensibility and safety. By separating the context engine from the execution logic, it ensures that LLMs have accurate project data while maintaining strict control over tool execution through various approval modes. The modularity allows for diverse frontends (CLI, TUI, VS Code) to share the same powerful backend agent and toolset.