QQcode

  ▇▇▇▇      ▇▇▇▇
▇▇    ▇▇  ▇▇    ▇▇
▇▇    ▇▇  ▇▇    ▇▇
▇▇  ▇▇▇▇  ▇▇  ▇▇▇▇
  ▇▇▇▇▇▇    ▇▇▇▇▇▇

Open-source CLI coding assistant.

QQcode is a command-line coding assistant powered by AI models. It provides a conversational interface to your codebase, allowing you to use natural language to explore, modify, and interact with your projects through a powerful set of tools.

Support: MacOS, Linux, Windows (Experimental).

Acknowledgement

QQcode is a fork of Mistral Vibe, the original CLI coding assistant developed by Mistral AI.

One-line install (recommended)

Linux and macOS

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

Windows

First, install uv

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then, use uv command below.

Using uv

uv tool install qqcode

Using pip

pip install qqcode

Features

Interactive Chat: A conversational AI agent that understands your requests and breaks down complex tasks.
Powerful Toolset: A suite of tools for file manipulation, code searching, version control, and command execution, right from the chat prompt.
- Read, write, and edit files.
- Execute shell commands in a stateful terminal (bash).
- Recursively search code with grep (with ripgrep support).
- Manage a todo list to track the agent's work.
- Agent Skills are loaded in on-demand to provide more context.
Project-Aware Context: QQcode automatically scans your project's file structure and Git status to provide relevant context to the agent, improving its understanding of your codebase.
Advanced CLI Experience: Built with modern libraries for a smooth and efficient workflow.
- Autocompletion for slash commands (/) and file paths (@).
- Persistent command history.
- Beautiful Themes.
Highly Configurable: Customize models, providers, tool permissions, and UI preferences through a simple config.toml file.
Safety First: Features tool execution approval.

Quick Start

Navigate to your project's root directory:
```
cd /path/to/your/project
```
Run QQcode:
```
qqcode
```
If this is your first time running QQcode, it will:
- Create a default configuration file at ~/.qqcode/config.toml
- Prompt you to enter your API key if it's not already configured
- Save your API key to ~/.qqcode/.env for future use

Start interacting with the agent!

> Can you find all instances of the word "TODO" in the project?

🤖 The user wants to find all instances of "TODO". The `grep` tool is perfect for this. I will use it to search the current directory.

> grep(pattern="TODO", path=".")

... (grep tool output) ...

🤖 I found the following "TODO" comments in your project.

Usage

Interactive Mode

Simply run qqcode to enter the interactive chat loop.

Multi-line Input: Press Ctrl+J or Shift+Enter for select terminals to insert a newline.
File Paths: Reference files in your prompt using the @ symbol for smart autocompletion (e.g., > Read the file @src/agent.py).
Shell Commands: Prefix any command with ! to execute it directly in your shell, bypassing the agent (e.g., > !ls -l).

You can start QQcode with a prompt with the following command:

qqcode "Refactor the main function in cli/main.py to be more modular."

Note: The --auto-approve flag automatically approves all tool executions without prompting. In interactive mode, you can also toggle auto-approve on/off using Shift+Tab.

Programmatic Mode

You can run QQcode non-interactively by piping input or using the --prompt flag. This is useful for scripting.

qqcode --prompt "Refactor the main function in cli/main.py to be more modular."

by default it will use auto-approve mode.

Slash Commands

Use slash commands for meta-actions and configuration changes during a session.

Skills

QQcode supports Skills, which work exactly like Claude Skills. Skills allow you to extend QQcode's capabilities with custom workflows, templates, and domain-specific expertise.

To create a skill, place your skill directory under .qqcode/skills/[your-skill] for it to be automatically registered and available to the agent. Each skill should contain a SKILL.md file that defines the skill's name, description, and instructions.

Example skill structure:

.qqcode/
  skills/
    my-skill/
      SKILL.md
      scripts/
      templates/

Skills can provide specialized workflows, context, and best practices for specific domains like frontend development, data analysis, or testing.

Configuration

QQcode is configured via a config.toml file. It looks for this file first in ./.qqcode/config.toml and then falls back to ~/.qqcode/config.toml.

Supported Providers

QQcode supports multiple AI providers:

Anthropic Claude Max subscription: Access Claude models with your Claude.ai subscription (run qqcode --login anthropic)
OpenRouter: Access multiple AI models through a single API
Mistral AI: Use Mistral's AI models directly

API Key Configuration

QQcode supports multiple ways to configure your API keys:

Interactive Setup (Recommended for first-time users): When you run QQcode for the first time or if your API key is missing, QQcode will prompt you to enter it. The key will be securely saved to ~/.qqcode/.env for future sessions.
Environment Variables: Set your API key as an environment variable:
```
export OPENROUTER_API_KEY="your_openrouter_api_key"
```
.env File: Create a .env file in ~/.qqcode/ and add your API keys:
```
OPENROUTER_API_KEY=your_openrouter_api_key
```
QQcode automatically loads API keys from ~/.qqcode/.env on startup. Environment variables take precedence over the .env file if both are set.

Note: The .env file is specifically for API keys and other provider credentials. General QQcode configuration should be done in config.toml.

Custom System Prompts

You can create custom system prompts to replace the default one (prompts/cli.md). Create a markdown file in the ~/.qqcode/prompts/ directory with your custom prompt content.

To use a custom system prompt, set the system_prompt_id in your configuration to match the filename (without the .md extension):

# Use a custom system prompt
system_prompt_id = "my_custom_prompt"

This will load the prompt from ~/.qqcode/prompts/my_custom_prompt.md.

Custom Agent Configurations

You can create custom agent configurations for specific use cases (e.g., red-teaming, specialized tasks) by adding agent-specific TOML files in the ~/.qqcode/agents/ directory.

To use a custom agent, run QQcode with the --agent flag:

qqcode --agent my_custom_agent

QQcode will look for a file named my_custom_agent.toml in the agents directory and apply its configuration.

Example custom agent configuration (~/.qqcode/agents/redteam.toml):

# Custom agent configuration for red-teaming
active_model = "devstral-2"
system_prompt_id = "redteam"

# Disable some tools for this agent
disabled_tools = ["edit", "write_file"]

# Override tool permissions for this agent
[tools.bash]
permission = "always"

[tools.read_file]
permission = "always"

Note: this implies that you have setup a redteam prompt names ~/.qqcode/prompts/redteam.md

MCP Server Configuration

You can configure MCP (Model Context Protocol) servers to extend QQcode's capabilities. Add MCP server configurations under the mcp_servers section:

# Example MCP server configurations
[[mcp_servers]]
name = "my_http_server"
transport = "http"
url = "http://localhost:8000"
headers = { "Authorization" = "Bearer my_token" }
api_key_env = "MY_API_KEY_ENV_VAR"
api_key_header = "Authorization"
api_key_format = "Bearer {token}"

[[mcp_servers]]
name = "my_streamable_server"
transport = "streamable-http"
url = "http://localhost:8001"
headers = { "X-API-Key" = "my_api_key" }

[[mcp_servers]]
name = "fetch_server"
transport = "stdio"
command = "uvx"
args = ["mcp-server-fetch"]

Supported transports:

http: Standard HTTP transport
streamable-http: HTTP transport with streaming support
stdio: Standard input/output transport (for local processes)

Key fields:

name: A short alias for the server (used in tool names)
transport: The transport type
url: Base URL for HTTP transports
headers: Additional HTTP headers
api_key_env: Environment variable containing the API key
command: Command to run for stdio transport
args: Additional arguments for stdio transport

MCP tools are named using the pattern {server_name}_{tool_name} and can be configured with permissions like built-in tools:

# Configure permissions for specific MCP tools
[tools.fetch_server_get]
permission = "always"

[tools.my_http_server_query]
permission = "ask"

Enable/disable tools with patterns

You can control which tools are active using enabled_tools and disabled_tools. These fields support exact names, glob patterns, and regular expressions.

Examples:

# Only enable tools that start with "serena_" (glob)
enabled_tools = ["serena_*"]

# Regex (prefix with re:) — matches full tool name (case-insensitive)
ena

Qqcode

Install / Use

README