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:

// 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 - Learn how to contribute
• Development Setup - Set up your dev environment
• Tools System - Deep dive into the tools architecture
• Subagents System - Learn about task delegation
• Configuration System - Understanding configuration