Configuration Management

Relevant source files

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

• vibe/core/config.py
• vibe/cli/entrypoint.py
• vibe/cli/textual_ui/widgets/config_app.py
• README.md
• CLAUDE.md

Configuration Management in QQcode is a centralized system built on Pydantic and TOML that governs how the AI agent interacts with users and the local environment. It manages AI provider credentials, model parameters, tool permissions, and UI preferences across different environments including CLI, TUI, and the VS Code extension.

The system supports a hierarchical loading strategy where global settings can be overridden by project-specific configurations or command-line arguments. This ensures that the coding assistant remains portable while allowing specialized behavior for specific repositories.

Sources: vibe/core/config.py, README.md:129-131

Core Architecture

The configuration system is centered around the VibeConfig class, which utilizes pydantic-settings to manage data validation and environment variable mapping. The system resolves configuration files by looking for a .qqcode/config.toml in the current working directory or its parents, falling back to a global configuration in the user's home directory.

Sources: vibe/core/config.py:28-36, CLAUDE.md:52-56

Configuration Data Flow

The following diagram illustrates how configuration is resolved from various sources and merged into the active state.

The diagram shows the priority of configuration sources where CLI overrides and project-local files take precedence over global defaults.
Sources: vibe/core/config.py:339-354, vibe/cli/entrypoint.py:126-140

Settings Components

The system is modularized into several configuration classes, each handling a specific domain of the application's behavior.

Component	Class	Purpose
Main Config	VibeConfig	High-level settings for models, themes, and tool paths.
Model	ModelConfig	Definitions for specific LLMs, including context limits and pricing.
Provider	ProviderConfig	API endpoints and authentication methods for AI services.
Project Context	ProjectContextConfig	Rules for scanning directories and project files.
Logging	SessionLoggingConfig	Settings for session persistence and log directories.
MCP	MCPServer	Configuration for Model Context Protocol server integrations.

Sources: vibe/core/config.py:108-251

Model and Provider Management

QQcode supports multiple AI backends (Mistral, Anthropic, and Generic OpenAI-compatible). Providers are identified by unique names and associated with specific API bases and authentication styles.

File and Path Resolution

The application uses a specific directory structure for its configuration assets. The base directory is determined by the QQCODE_HOME environment variable, defaulting to ~/.qqcode.

Key Paths and Files

• config.toml: The primary configuration file for settings.
• .env: Secure storage for API keys (e.g., MISTRAL_API_KEY).
• agents/: Directory for custom agent profiles (TOML).
• prompts/: Custom system prompt markdown files.
• instructions.md: User-defined instructions loaded into the system prompt.

Sources: vibe/core/config.py:13-26, vibe/cli/entrypoint.py:146-156

Prompt Resolution Logic

The system prompt is resolved through the system_prompt property in VibeConfig. It checks for built-in prompts first, then looks for matching .md files in the PROMPT_DIR.

# vibe/core/config.py:318-326
@property
def system_prompt(self) -> str:
    try:
        return SystemPrompt[self.system_prompt_id.upper()].read()
    except KeyError:
        pass

    custom_sp_path = (PROMPT_DIR / self.system_prompt_id).with_suffix(".md")
    if not custom_sp_path.is_file():
        raise MissingPromptFileError(self.system_prompt_id, str(PROMPT_DIR))
    return custom_sp_path.read_text()

Runtime Configuration and TUI

Users can modify active settings during an interactive session through a dedicated Configuration App (TUI). This interface allows cycling through available providers and models defined in the configuration.

Selection Synchronization

The ConfigApp ensures that when a provider is changed, the available models are filtered and updated to maintain consistency.

Tool Configuration and Permissions

Tools are configured individually with permissions that control execution safety. Patterns (glob and regex) can be used to enable or disable groups of tools.

• enabled_tools: Explicit list of names or patterns. If set, all others are disabled.
• disabled_tools: List of tools/patterns to exclude.
• tool_paths: Directories searched for custom tool implementations.

Sources: vibe/core/config.py:279-301, README.md:204-219

Configuration Migration and Defaults

The system includes a migration mechanism to ensure configuration files stay up-to-date with current application requirements, such as updating the auto_compact_threshold.

Migration Logic

If a config.toml exists, the _migrate method checks for specific keys and updates values if they match old defaults (e.g., increasing context limits).

Sources: vibe/core/config.py:465-484

Summary

Configuration Management in QQcode provides a robust foundation for AI agent operations by blending static TOML definitions with dynamic environment variables and runtime overrides. Through its Pydantic-based validation, the system ensures that complex dependencies between providers, models, and tool permissions remain consistent across the CLI and VS Code interfaces. This tiered approach allows users to maintain global preferences while tailoring the assistant's behavior to specific project needs via project-local configuration files.