Introduction to QQcode
Relevant source files
The following files were used as context for generating this wiki page:
QQcode is an open-source command-line interface (CLI) coding assistant designed to provide a conversational interface for interacting with local codebases. Powered by various Large Language Models (LLMs), it enables developers to explore, modify, and manage projects using natural language. The system integrates a suite of tools for file manipulation, shell command execution, and version control, while remaining highly configurable via a config.toml file.
Sources: README.md:1-20, CLAUDE.md:5-10
Project Overview and Core Capabilities
QQcode operates as an agentic assistant that can break down complex, multi-step tasks into executable steps. It supports major operating systems including macOS, Linux, and Windows (experimental). Key capabilities include project-aware context scanning, streaming responses, and a robust toolset.
Key Features
| Feature | Description |
|---|---|
| Interactive Chat | Conversational AI understanding requests and breaking down tasks. |
| Project-Aware Context | Scans file structure and Git status to inform the agent. |
| Tool Execution | Executes shell commands, searches code with grep, and manages files. |
| Safety Approval | Features a tool execution approval mechanism for security. |
| Multiple Interfaces | Accessible via CLI (TUI), programmatic prompts, and a VS Code extension. |
Sources: README.md:43-69, CLAUDE.md:7-10
System Architecture
The project is structured into core logic, CLI/TUI interfaces, and external integrations like the Agent Client Protocol (ACP) and VS Code extension.
Package Structure
vibe/core/: Contains the centralAgentclass that orchestrates LLM interactions and tool execution.vibe/cli/: The main entry point featuring a Textual-based Terminal User Interface (TUI).vibe/tools/: A system for discovering and instantiating built-in tools (bash, grep, edit) and MCP (Model Context Protocol) integrations.vibe/acp/: Implements the Agent Client Protocol to expose QQcode as an ACP-compatible agent.
Sources: CLAUDE.md:27-46
High-Level Component Interaction
The following diagram illustrates how the User interacts with the CLI, which then coordinates between the LLM and the local filesystem tools.
Context and Prompt Engineering
QQcode utilizes a sophisticated context provider to ensure the LLM understands the current state of the project. This involves scanning the directory structure and gathering Git metadata.
Project Context Provider
The ProjectContextProvider class (found in vibe/core/system_prompt.py) is responsible for building a representation of the codebase. It respects .gitignore patterns and applies limits on recursion depth and file counts to manage token usage.
- Directory Structure: Generates a tree-like view of the root directory.
- Git Status: Captures current branch, status (clean/dirty), and recent commits.
- System Prompts: Dynamically constructs prompts based on the operating system (e.g., providing specific rules for Windows CMD compatibility).
Sources: vibe/core/system_prompt.py:44-60, vibe/core/system_prompt.py:180-210, vibe/core/system_prompt.py:305-320
Git Status Logic
Sources: vibe/core/system_prompt.py:180-240
Execution Modes
QQcode supports different operational modes to balance automation and safety.
- Plan Mode: The agent explores the codebase using read-only tools and submits a markdown plan for user review before making changes.
- Interactive Mode: Standard conversational mode where the agent performs actions, often requiring manual approval for specific tool calls.
- Auto-Approve: The agent executes all tools without prompting the user for permission.
Sources: README.md:104-108, vscode-extension/src/qqcodeBackend.ts:168-175, vibe/core/prompts/plan_mode.md:1-15
VS Code Integration
The project includes a VS Code extension that interacts with the QQcode CLI as a subprocess using the --output vscode flag.
Communication Flow
The extension's backend (QQCodeBackend) spawns the CLI and communicates via JSON streaming events. It handles events such as thread.started, item.updated (for text streaming), and tool.approval_required.
Technical Requirements and Setup
QQcode is built with Python 3.12+ and utilizes the uv package manager for dependency handling.
| Requirement | Details |
|---|---|
| Python | Version 3.12 or higher. |
| Package Manager | uv (recommended) or pip. |
| Dependencies | Pydantic v2, Textual, Anthropic/Mistral SDKs, MCP. |
| Configuration | ~/.qqcode/config.toml or project-local .qqcode/config.toml. |
Sources: README.md:25-40, pyproject.toml:5-35, AGENTS.md:100-115
Conclusion
QQcode serves as a bridge between high-level natural language intent and low-level filesystem/terminal operations. By combining an extensible tool system with project-aware context and multiple safety modes, it provides a versatile environment for AI-assisted software development across various interfaces.
Sources: README.md:14-20, CLAUDE.md:5-10