Installation & Prerequisites

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• CONTRIBUTING.md
• pyproject.toml
• vibe/core/config.py
• vscode-extension/README.md
• action.yml

QQcode is an open-source CLI coding assistant that provides a conversational interface to your codebase. To ensure successful deployment and operation, several prerequisites and installation methods are supported depending on the environment (local CLI, VSCode, or GitHub Actions).

Sources: README.md:1-25, CLAUDE.md:1-10

System Requirements & Prerequisites

The core technical requirements for running QQcode are centered around Python versioning and specific package management tools.

Core Requirements

• Python Version: Requires Python 3.12 or higher.
• Operating Systems: macOS, Linux, and Windows (Experimental).
• Package Manager: uv is the recommended tool for managing dependencies and execution environments.

Sources: README.md:12-18, pyproject.toml:6, AGENTS.md:1-5

Development Tools

For developers intending to modify or contribute to the repository, the following tools are utilized:

• Ruff: For linting and formatting.
• Pyright: For static type checking.
• Pre-commit: For automated hook execution.

Sources: CLAUDE.md:15-38, CONTRIBUTING.md:95-125

Installation Methods

Recommended One-Line Install

For most users on Unix-like systems, a shell script is provided for rapid installation.

# Linux and macOS
curl -LsSf https://raw.githubusercontent.com/qnguyen3/qqcode/main/scripts/install.sh | bash

Sources: README.md:27-33

Using uv (Standard Method)

The preferred method for installing QQcode is via uv, which ensures environment isolation and consistency.

# Global tool installation
uv tool install qqcode

# Development environment setup
uv sync --all-extras

Sources: README.md:46-48, CLAUDE.md:14-16

Platform-Specific Instructions

Platform	Recommended Command	Notes
Windows	powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"	Requires installing uv first.
Linux/macOS	curl -LsSf ... | bash	Direct install script supported.
Python/pip	pip install qqcode	Standard fallback method.

Sources: README.md:35-54

VSCode Extension Setup

The QQCode Companion extension provides a GUI layer over the CLI tool. It requires the CLI to be pre-installed and available in the system path.

Installation Steps

1. Install CLI: Ensure qqcode is installed via uv or pip.
2. Verify Capability: The extension requires the --output vscode feature.
3. Install Extension: Use code --install-extension qqcode-companion-0.1.0.vsix or install via the VSCode Marketplace (planned).

Sources: vscode-extension/README.md:14-35

Extension Communication Flow

The diagram below illustrates how the VSCode extension interacts with the underlying QQcode CLI.

The extension spawns the CLI as a subprocess using the command qqcode --prompt "..." --output vscode.
Sources: vscode-extension/README.md:46-52

Initial Configuration & Onboarding

Upon the first execution of qqcode, the system initiates an onboarding flow to establish necessary configuration files and credentials.

Configuration Hierarchy

QQcode searches for configuration in the following order:

1. ./.qqcode/config.toml (Project-local)
2. ~/.qqcode/config.toml (Global)
3. QQCODE_HOME environment variable (Custom override)

Sources: README.md:118-122, vibe/core/config.py:31-45

API Key Management

QQcode requires API keys for AI providers (e.g., Anthropic, Mistral, OpenRouter). These can be provided during the interactive setup or via environment variables.

Source	File/Variable	Usage
Interactive	~/.qqcode/.env	Securely saved during first run.
Environment	OPENROUTER_API_KEY	Overrides .env file settings.
GitHub Action	MISTRAL_API_KEY	Passed via action.yml inputs.

Sources: README.md:139-158, action.yml:14-16, vibe/core/config.py:48-55

Dependency Specification

The project defines its runtime and development dependencies within pyproject.toml.

[project]
requires-python = ">=3.12"
dependencies = [
    "agent-client-protocol==0.6.3",
    "pydantic>=2.12.4",
    "textual>=1.0.0",
    "mcp>=1.14.0",
    "anthropic>=0.75.0"
]

Sources: pyproject.toml:6-34

Summary

Installation of QQcode focuses on providing a modern Python 3.12+ environment managed by uv. The system supports multiple interfaces—CLI, VSCode, and GitHub Actions—all of which rely on a centralized configuration structure located in the user's home directory. Successful setup concludes with the generation of a config.toml file and the secure storage of API credentials.