> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/QwenLM/qwen-code/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> Understanding Qwen Code's architecture and core components

# Architecture Overview

Qwen Code is a terminal-based AI coding agent built with a modular architecture that separates concerns between user interface, business logic, and tool execution.

## Core Components

The project is organized into specialized packages:

### 1. CLI Package (`packages/cli`)

**Purpose:** The user-facing interface that handles all terminal interactions.

**Key Responsibilities:**

* **Input Processing:** Handles user input through:
  * Direct text entry for natural language prompts
  * Slash commands (e.g., `/help`, `/clear`, `/model`)
  * At commands (`@file` for including file content)
  * Exclamation mark commands (`!command` for shell execution)
* **History Management:** Maintains conversation history and enables session resumption
* **Display Rendering:** Formats and presents responses with syntax highlighting and proper formatting using Ink (React for CLI)
* **Theme & UI Customization:** Supports customizable themes and UI elements
* **Configuration Management:** Manages settings through JSON files, environment variables, and CLI arguments

**Technology Stack:**

* React 19.x with Ink for terminal UI
* Node.js 20+ runtime
* TypeScript for type safety

### 2. Core Package (`packages/core`)

**Purpose:** The backend engine that orchestrates AI interactions and tool execution.

**Key Responsibilities:**

* **API Client:** Communicates with Qwen model API and other LLM providers
* **Prompt Construction:** Builds appropriate prompts incorporating history and tool definitions
* **Tool Registration & Execution:** Manages the registry of available tools and executes them based on model requests
* **State Management:** Maintains conversation and session state
* **Configuration:** Handles server-side configuration and settings

**Key Subsystems:**

#### Tool System (`packages/core/src/tools/`)

The tool system provides the model with capabilities to interact with the local environment:

* **File Operations:** Read, Write, Edit, Glob, Grep
* **Shell Commands:** Execute system commands with user approval
* **Task Delegation:** Launch specialized subagents
* **Memory Management:** Save and retrieve long-term memories
* **MCP Integration:** Connect to Model Context Protocol servers
* **LSP Integration:** Language Server Protocol support
* **Web Tools:** Web fetch and search capabilities

#### Subagent System (`packages/core/src/subagents/`)

Enables task delegation to specialized agents:

* Configuration stored as Markdown files with YAML frontmatter
* Support for project-level and user-level subagents
* Built-in agents for common tasks
* Event-driven architecture for real-time UI updates
* Stateless, single-use execution model

#### Configuration System (`packages/core/src/config/`)

Hierarchical configuration loading with precedence:

1. Command-line arguments (highest priority)
2. Environment variables
3. Project settings (`.qwen/settings.json`)
4. User settings (`~/.qwen/settings.json`)
5. System settings files
6. Default values (lowest priority)

### 3. Additional Packages

* **`packages/sdk-typescript`** - TypeScript SDK for programmatic access
* **`packages/sdk-java`** - Java SDK
* **`packages/vscode-ide-companion`** - VS Code extension
* **`packages/zed-extension`** - Zed editor extension
* **`packages/webui`** - Web UI components
* **`packages/test-utils`** - Shared testing utilities

## Interaction Flow

A typical interaction follows this flow:

```
┌──────────────┐
│              │
│  User Input  │
│              │
└──────┬───────┘
       │
       v
┌──────────────────────────────────────┐
│                                      │
│  CLI Package (packages/cli)          │
│  - Parse input                       │
│  - Format display                    │
│  - Manage history                    │
│                                      │
└──────────────┬───────────────────────┘
               │
               v
┌──────────────────────────────────────┐
│                                      │
│  Core Package (packages/core)        │
│  - Construct prompt                  │
│  - Call model API                    │
│  - Process response                  │
│                                      │
└──────────────┬───────────────────────┘
               │
       ┌───────┴───────┐
       │               │
       v               v
┌──────────┐    ┌──────────────┐
│          │    │              │
│  Model   │    │  Tool        │
│  API     │<───│  Execution   │
│          │    │              │
└──────────┘    └──────────────┘
       │
       v
┌──────────────┐
│              │
│  User sees   │
│  response    │
│              │
└──────────────┘
```

### Detailed Flow Steps:

1. **User Input:** User types a prompt or command into the terminal (handled by CLI)
2. **Request to Core:** CLI sends the input to Core package
3. **Prompt Construction:** Core constructs a prompt with:
   * Conversation history
   * Available tool definitions
   * System prompts
   * Context files (QWEN.md, AGENTS.md)
4. **API Call:** Core sends the prompt to the model API
5. **Model Response:** Model returns either:
   * A direct text response
   * A request to use one or more tools
6. **Tool Execution (if needed):**
   * Core validates tool parameters
   * For modifying operations: User confirmation required
   * For read-only operations: May execute automatically
   * Tool executes and returns results
   * Results sent back to model for final response
7. **Response to CLI:** Core sends the final response to CLI
8. **Display:** CLI formats and displays the response with syntax highlighting

## Configuration Architecture

### Configuration Layers

Qwen Code uses a layered configuration system with clear precedence:

```typescript theme={null}
// Priority (highest to lowest):
1. CLI arguments (--model, --temperature, etc.)
2. Environment variables (QWEN_MODEL, OPENAI_API_KEY)
3. Project settings (.qwen/settings.json)
4. User settings (~/.qwen/settings.json)
5. System settings
6. Built-in defaults
```

### Key Configuration Categories:

* **General Settings:** vim mode, editor preferences, auto-update
* **UI Settings:** themes, banner visibility, footer display
* **Model Settings:** model selection, temperature, session limits
* **Context Settings:** context file names, directory inclusion, file filtering
* **Tool Settings:** approval modes, sandboxing, tool restrictions
* **Privacy Settings:** usage statistics, telemetry
* **Advanced Settings:** debug options, custom commands

## Key Design Principles

### Modularity

Separating CLI from Core allows:

* Independent development and testing
* Different frontends for the same backend
* Clear separation of concerns
* Easier maintenance and debugging

### Extensibility

The tool system is designed for easy extension:

* All tools implement `BaseDeclarativeTool`
* Tools self-describe their parameters using JSON Schema
* New tools automatically appear in model's context
* MCP servers can add tools dynamically

### Security

* **Sandboxing:** Optional Docker/Podman sandbox for code execution
* **Approval Mechanisms:** User confirmation for dangerous operations
* **Path Validation:** All file operations validated against workspace boundaries
* **Command Restrictions:** Configurable allowlist/blocklist for shell commands
* **Trusted Folders:** Special handling for trusted project directories

### User Experience

* **Rich Terminal UI:** Syntax highlighting, progress indicators, diffs
* **Interactive Mode:** Real-time feedback and streaming responses
* **Headless Mode:** Non-interactive operation for automation
* **Customization:** Themes, keybindings, and behavior settings
* **Error Handling:** Clear, actionable error messages

## Technology Stack

* **Runtime:** Node.js 20+
* **Language:** TypeScript 5.3+ with strict mode
* **Build Tool:** esbuild for fast compilation
* **Testing:** Vitest for unit and integration tests
* **Linting:** ESLint + Prettier for code quality
* **UI Framework:** Ink (React for CLI)
* **Package Manager:** npm with workspaces
* **Module System:** ES modules with `.js` extensions in imports

## File Structure

```
qwen-code/
├── packages/
│   ├── cli/              # Terminal interface
│   │   ├── src/
│   │   │   ├── commands/ # Slash commands
│   │   │   ├── ui/       # Ink components
│   │   │   └── index.ts  # Entry point
│   │   └── package.json
│   ├── core/             # Backend logic
│   │   ├── src/
│   │   │   ├── config/   # Configuration system
│   │   │   ├── tools/    # Tool implementations
│   │   │   ├── subagents/# Subagent system
│   │   │   ├── services/ # Business services
│   │   │   ├── core/     # Model API clients
│   │   │   └── utils/    # Utilities
│   │   └── package.json
│   └── [other packages]
├── scripts/              # Build and utility scripts
├── docs/                 # Documentation
├── integration-tests/    # E2E tests
└── package.json          # Root package
```

## Next Steps

* [Contributing Guidelines](./contributing.mdx) - Learn how to contribute
* [Development Setup](./development-setup.mdx) - Set up your dev environment
* [Tools System](./tools-system.mdx) - Deep dive into the tools architecture
* [Subagents System](./subagents-system.mdx) - Learn about task delegation
* [Configuration System](./configuration-system.mdx) - Understanding configuration