[](https://www.npmjs.com/package/@qwen-code/qwen-code)
[](./LICENSE)
[](https://nodejs.org/)
[](https://www.npmjs.com/package/@qwen-code/qwen-code)
**An open-source AI agent that lives in your terminal.**
中文 |
Deutsch |
français |
日本語 |
Русский |
Português (Brasil)
> 🎉 **News (2026-02-16)**: Qwen3.5-Plus is now live! Sign in via Qwen OAuth to use it directly, or get an API key from [Alibaba Cloud ModelStudio](https://modelstudio.console.alibabacloud.com?tab=doc#/doc/?type=model&url=2840914_2&modelId=group-qwen3.5-plus) to access it through the OpenAI-compatible API.
Qwen Code is an open-source AI agent for the terminal, optimized for [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder). It helps you understand large codebases, automate tedious work, and ship faster.
## Why Qwen Code?
- **Multi-protocol, OAuth free tier**: use OpenAI / Anthropic / Gemini-compatible APIs, or sign in with Qwen OAuth for 1,000 free requests/day.
- **Open-source, co-evolving**: both the framework and the Qwen3-Coder model are open-source—and they ship and evolve together.
- **Agentic workflow, feature-rich**: rich built-in tools (Skills, SubAgents) for a full agentic workflow and a Claude Code-like experience.
- **Terminal-first, IDE-friendly**: built for developers who live in the command line, with optional integration for VS Code, Zed, and JetBrains IDEs.
## Installation
### Quick Install (Recommended)
#### Linux / macOS
```bash
bash -c "$(curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh)"
```
#### Windows (Run as Administrator CMD)
```cmd
curl -fsSL -o %TEMP%\install-qwen.bat https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat && %TEMP%\install-qwen.bat
```
> **Note**: It's recommended to restart your terminal after installation to ensure environment variables take effect.
### Manual Installation
#### Prerequisites
Make sure you have Node.js 20 or later installed. Download it from [nodejs.org](https://nodejs.org/en/download).
#### NPM
```bash
npm install -g @qwen-code/qwen-code@latest
```
#### Homebrew (macOS, Linux)
```bash
brew install qwen-code
```
## Quick Start
```bash
# Start Qwen Code (interactive)
qwen
# Then, in the session:
/help
/auth
```
On first use, you'll be prompted to sign in. You can run `/auth` anytime to switch authentication methods.
Example prompts:
```text
What does this project do?
Explain the codebase structure.
Help me refactor this function.
Generate unit tests for this module.
```
Click to watch a demo video
Coding Plan (Alibaba Cloud Bailian) — fixed monthly fee, higher quotas
```json { "modelProviders": { "openai": [ { "id": "qwen3.5-plus", "name": "qwen3.5-plus (Coding Plan)", "baseUrl": "https://coding.dashscope.aliyuncs.com/v1", "description": "qwen3.5-plus with thinking enabled from Bailian Coding Plan", "envKey": "BAILIAN_CODING_PLAN_API_KEY", "generationConfig": { "extra_body": { "enable_thinking": true } } }, { "id": "qwen3-coder-plus", "name": "qwen3-coder-plus (Coding Plan)", "baseUrl": "https://coding.dashscope.aliyuncs.com/v1", "description": "qwen3-coder-plus from Bailian Coding Plan", "envKey": "BAILIAN_CODING_PLAN_API_KEY" }, { "id": "qwen3-coder-next", "name": "qwen3-coder-next (Coding Plan)", "baseUrl": "https://coding.dashscope.aliyuncs.com/v1", "description": "qwen3-coder-next with thinking enabled from Bailian Coding Plan", "envKey": "BAILIAN_CODING_PLAN_API_KEY", "generationConfig": { "extra_body": { "enable_thinking": true } } }, { "id": "glm-4.7", "name": "glm-4.7 (Coding Plan)", "baseUrl": "https://coding.dashscope.aliyuncs.com/v1", "description": "glm-4.7 with thinking enabled from Bailian Coding Plan", "envKey": "BAILIAN_CODING_PLAN_API_KEY", "generationConfig": { "extra_body": { "enable_thinking": true } } }, { "id": "kimi-k2.5", "name": "kimi-k2.5 (Coding Plan)", "baseUrl": "https://coding.dashscope.aliyuncs.com/v1", "description": "kimi-k2.5 with thinking enabled from Bailian Coding Plan", "envKey": "BAILIAN_CODING_PLAN_API_KEY", "generationConfig": { "extra_body": { "enable_thinking": true } } } ] }, "env": { "BAILIAN_CODING_PLAN_API_KEY": "sk-xxxxxxxxxxxxx" }, "security": { "auth": { "selectedType": "openai" } }, "model": { "name": "qwen3-coder-plus" } } ``` > Subscribe to the Coding Plan and get your API key at [Alibaba Cloud Bailian](https://modelstudio.console.aliyun.com/?tab=dashboard#/efm/coding_plan).Multiple providers (OpenAI + Anthropic + Gemini)
```json { "modelProviders": { "openai": [ { "id": "gpt-4o", "name": "GPT-4o", "envKey": "OPENAI_API_KEY", "baseUrl": "https://api.openai.com/v1" } ], "anthropic": [ { "id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4", "envKey": "ANTHROPIC_API_KEY" } ], "gemini": [ { "id": "gemini-2.5-pro", "name": "Gemini 2.5 Pro", "envKey": "GEMINI_API_KEY" } ] }, "env": { "OPENAI_API_KEY": "sk-xxxxxxxxxxxxx", "ANTHROPIC_API_KEY": "sk-ant-xxxxxxxxxxxxx", "GEMINI_API_KEY": "AIzaxxxxxxxxxxxxx" }, "security": { "auth": { "selectedType": "openai" } }, "model": { "name": "gpt-4o" } } ```Enable thinking mode (for supported models like qwen3.5-plus)
```json { "modelProviders": { "openai": [ { "id": "qwen3.5-plus", "name": "qwen3.5-plus (thinking)", "envKey": "DASHSCOPE_API_KEY", "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", "generationConfig": { "extra_body": { "enable_thinking": true } } } ] }, "env": { "DASHSCOPE_API_KEY": "sk-xxxxxxxxxxxxx" }, "security": { "auth": { "selectedType": "openai" } }, "model": { "name": "qwen3.5-plus" } } ```✅ Support OpenAI Protocol
✅ Settings
✅ OAuth
✅ Cache Control
✅ Memory
✅ Compress
✅ Theme | Better UI
OnBoarding
LogView
✅ Session
Permission
🔄 Cross-platform Compatibility
✅ Coding Plan
✅ Anthropic Provider
✅ Multimodal Input
✅ Unified WebUI | | Coding Workflow | ✅ Slash Commands
✅ MCP
✅ PlanMode
✅ TodoWrite
✅ SubAgent
✅ Multi Model
✅ Chat Management
✅ Tools (WebFetch, Bash, TextSearch, FileReadFile, EditFile) | 🔄 Hooks
✅ Skill
✅ Headless Mode
✅ Tools (WebSearch)
✅ LSP Support
✅ Concurrent Runner | | Building Open Capabilities | ✅ Custom Commands | ✅ QwenCode SDK
✅ Extension System | | Integrating Community Ecosystem | | ✅ VSCode Plugin
✅ ACP/Zed
✅ GHA | | Administrative Capabilities | ✅ Stats
✅ Feedback | Costs
Dashboard
✅ User Feedback Dialog | > For more details, please see the list below. ## Features #### Completed Features | Feature | Version | Description | Category | Phase | | ----------------------- | --------- | ------------------------------------------------------- | ------------------------------- | ----- | | **Coding Plan** | `V0.10.0` | Alibaba Cloud Coding Plan authentication & models | User Experience | 2 | | Unified WebUI | `V0.9.0` | Shared WebUI component library for VSCode/CLI | User Experience | 2 | | Export Chat | `V0.8.0` | Export sessions to Markdown/HTML/JSON/JSONL | User Experience | 2 | | Extension System | `V0.8.0` | Full extension management with slash commands | Building Open Capabilities | 2 | | LSP Support | `V0.7.0` | Experimental LSP service (`--experimental-lsp`) | Coding Workflow | 2 | | Anthropic Provider | `V0.7.0` | Anthropic API provider support | User Experience | 2 | | User Feedback Dialog | `V0.7.0` | In-app feedback collection with fatigue mechanism | Administrative Capabilities | 2 | | Concurrent Runner | `V0.6.0` | Batch CLI execution with Git integration | Coding Workflow | 2 | | Multimodal Input | `V0.6.0` | Image, PDF, audio, video input support | User Experience | 2 | | Skill | `V0.6.0` | Extensible custom AI skills (experimental) | Coding Workflow | 2 | | Github Actions | `V0.5.0` | qwen-code-action and automation | Integrating Community Ecosystem | 1 | | VSCode Plugin | `V0.5.0` | VSCode extension plugin | Integrating Community Ecosystem | 1 | | QwenCode SDK | `V0.4.0` | Open SDK for third-party integration | Building Open Capabilities | 1 | | Session | `V0.4.0` | Enhanced session management | User Experience | 1 | | i18n | `V0.3.0` | Internationalization and multilingual support | User Experience | 1 | | Headless Mode | `V0.3.0` | Headless mode (non-interactive) | Coding Workflow | 1 | | ACP/Zed | `V0.2.0` | ACP and Zed editor integration | Integrating Community Ecosystem | 1 | | Terminal UI | `V0.1.0+` | Interactive terminal user interface | User Experience | 1 | | Settings | `V0.1.0+` | Configuration management system | User Experience | 1 | | Theme | `V0.1.0+` | Multi-theme support | User Experience | 1 | | Support OpenAI Protocol | `V0.1.0+` | Support for OpenAI API protocol | User Experience | 1 | | Chat Management | `V0.1.0+` | Session management (save, restore, browse) | Coding Workflow | 1 | | MCP | `V0.1.0+` | Model Context Protocol integration | Coding Workflow | 1 | | Multi Model | `V0.1.0+` | Multi-model support and switching | Coding Workflow | 1 | | Slash Commands | `V0.1.0+` | Slash command system | Coding Workflow | 1 | | Tool: Bash | `V0.1.0+` | Shell command execution tool (with is_background param) | Coding Workflow | 1 | | Tool: FileRead/EditFile | `V0.1.0+` | File read/write and edit tools | Coding Workflow | 1 | | Custom Commands | `V0.1.0+` | Custom command loading | Building Open Capabilities | 1 | | Feedback | `V0.1.0+` | Feedback mechanism (/bug command) | Administrative Capabilities | 1 | | Stats | `V0.1.0+` | Usage statistics and quota display | Administrative Capabilities | 1 | | Memory | `V0.0.9+` | Project-level and global memory management | User Experience | 1 | | Cache Control | `V0.0.9+` | Prompt caching control (Anthropic, DashScope) | User Experience | 1 | | PlanMode | `V0.0.14` | Task planning mode | Coding Workflow | 1 | | Compress | `V0.0.11` | Chat compression mechanism | User Experience | 1 | | SubAgent | `V0.0.11` | Dedicated sub-agent system | Coding Workflow | 1 | | TodoWrite | `V0.0.10` | Task management and progress tracking | Coding Workflow | 1 | | Tool: TextSearch | `V0.0.8+` | Text search tool (grep, supports .qwenignore) | Coding Workflow | 1 | | Tool: WebFetch | `V0.0.7+` | Web content fetching tool | Coding Workflow | 1 | | Tool: WebSearch | `V0.0.7+` | Web search tool (using Tavily API) | Coding Workflow | 1 | | OAuth | `V0.0.5+` | OAuth login authentication (Qwen OAuth) | User Experience | 1 | #### Features to Develop | Feature | Priority | Status | Description | Category | | ---------------------------- | -------- | ----------- | --------------------------------- | --------------------------- | | Better UI | P1 | Planned | Optimized terminal UI interaction | User Experience | | OnBoarding | P1 | Planned | New user onboarding flow | User Experience | | Permission | P1 | Planned | Permission system optimization | User Experience | | Cross-platform Compatibility | P1 | In Progress | Windows/Linux/macOS compatibility | User Experience | | LogView | P2 | Planned | Log viewing and debugging feature | User Experience | | Hooks | P2 | In Progress | Extension hooks system | Coding Workflow | | Costs | P2 | Planned | Cost tracking and analysis | Administrative Capabilities | | Dashboard | P2 | Planned | Management dashboard | Administrative Capabilities | #### Distinctive Features to Discuss | Feature | Status | Description | | ---------------- | -------- | ----------------------------------------------------- | | Home Spotlight | Research | Project discovery and quick launch | | Competitive Mode | Research | Competitive mode | | Pulse | Research | User activity pulse analysis (OpenAI Pulse reference) | | Code Wiki | Research | Project codebase wiki/documentation system | ================================================ FILE: docs/developers/sdk-java.md ================================================ # Qwen Code Java SDK The Qwen Code Java SDK is a minimum experimental SDK for programmatic access to Qwen Code functionality. It provides a Java interface to interact with the Qwen Code CLI, allowing developers to integrate Qwen Code capabilities into their Java applications. ## Requirements - Java >= 1.8 - Maven >= 3.6.0 (for building from source) - qwen-code >= 0.5.0 ### Dependencies - **Logging**: ch.qos.logback:logback-classic - **Utilities**: org.apache.commons:commons-lang3 - **JSON Processing**: com.alibaba.fastjson2:fastjson2 - **Testing**: JUnit 5 (org.junit.jupiter:junit-jupiter) ## Installation Add the following dependency to your Maven `pom.xml`: ```xml
Windows: `C:\ProgramData\qwen-code\system-defaults.json`
macOS: `/Library/Application Support/QwenCode/system-defaults.json`
The path can be overridden using the `QWEN_CODE_SYSTEM_DEFAULTS_PATH` environment variable. | Provides a base layer of system-wide default settings. These settings have the lowest precedence and are intended to be overridden by user, project, or system override settings. | | User settings file | `~/.qwen/settings.json` (where `~` is your home directory). | Applies to all Qwen Code sessions for the current user. | | Project settings file | `.qwen/settings.json` within your project's root directory. | Applies only when running Qwen Code from that specific project. Project settings override user settings. | | System settings file | Linux： `/etc/qwen-code/settings.json`
Windows: `C:\ProgramData\qwen-code\settings.json`
macOS: `/Library/Application Support/QwenCode/settings.json`
The path can be overridden using the `QWEN_CODE_SYSTEM_SETTINGS_PATH` environment variable. | Applies to all Qwen Code sessions on the system, for all users. System settings override user and project settings. May be useful for system administrators at enterprises to have controls over users' Qwen Code setups. | > [!note] > > **Note on environment variables in settings:** String values within your `settings.json` files can reference environment variables using either `$VAR_NAME` or `${VAR_NAME}` syntax. These variables will be automatically resolved when the settings are loaded. For example, if you have an environment variable `MY_API_TOKEN`, you could use it in `settings.json` like this: `"apiKey": "$MY_API_TOKEN"`. ### The `.qwen` directory in your project In addition to a project settings file, a project's `.qwen` directory can contain other project-specific files related to Qwen Code's operation, such as: - [Custom sandbox profiles](../features/sandbox) (e.g. `.qwen/sandbox-macos-custom.sb`, `.qwen/sandbox.Dockerfile`). - [Agent Skills](../features/skills) under `.qwen/skills/` (each Skill is a directory containing a `SKILL.md`). ### Configuration migration Qwen Code automatically migrates legacy configuration settings to the new format. Old settings files are backed up before migration. The following settings have been renamed from negative (`disable*`) to positive (`enable*`) naming: | Old Setting | New Setting | Notes | | ---------------------------------------- | ------------------------------------------- | ---------------------------------- | | `disableAutoUpdate` + `disableUpdateNag` | `general.enableAutoUpdate` | Consolidated into a single setting | | `disableLoadingPhrases` | `ui.accessibility.enableLoadingPhrases` | | | `disableFuzzySearch` | `context.fileFiltering.enableFuzzySearch` | | | `disableCacheControl` | `model.generationConfig.enableCacheControl` | | > [!note] > > **Boolean value inversion:** When migrating, boolean values are inverted (e.g., `disableAutoUpdate: true` becomes `enableAutoUpdate: false`). #### Consolidation policy for `disableAutoUpdate` and `disableUpdateNag` When both legacy settings are present with different values, the migration follows this policy: if **either** `disableAutoUpdate` **or** `disableUpdateNag` is `true`, then `enableAutoUpdate` becomes `false`: | `disableAutoUpdate` | `disableUpdateNag` | Migrated `enableAutoUpdate` | | ------------------- | ------------------ | --------------------------- | | `false` | `false` | `true` | | `false` | `true` | `false` | | `true` | `false` | `false` | | `true` | `true` | `false` | ### Available settings in `settings.json` Settings are organized into categories. All settings should be placed within their corresponding top-level category object in your `settings.json` file. #### general | Setting | Type | Description | Default | | ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `general.preferredEditor` | string | The preferred editor to open files in. | `undefined` | | `general.vimMode` | boolean | Enable Vim keybindings. | `false` | | `general.enableAutoUpdate` | boolean | Enable automatic update checks and installations on startup. | `true` | | `general.gitCoAuthor` | boolean | Automatically add a Co-authored-by trailer to git commit messages when commits are made through Qwen Code. | `true` | | `general.checkpointing.enabled` | boolean | Enable session checkpointing for recovery. | `false` | | `general.defaultFileEncoding` | string | Default encoding for new files. Use `"utf-8"` (default) for UTF-8 without BOM, or `"utf-8-bom"` for UTF-8 with BOM. Only change this if your project specifically requires BOM. | `"utf-8"` | #### output | Setting | Type | Description | Default | Possible Values | | --------------- | ------ | ----------------------------- | -------- | ------------------ | | `output.format` | string | The format of the CLI output. | `"text"` | `"text"`, `"json"` | #### ui | Setting | Type | Description | Default | | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `ui.theme` | string | The color theme for the UI. See [Themes](../configuration/themes) for available options. | `undefined` | | `ui.customThemes` | object | Custom theme definitions. | `{}` | | `ui.hideWindowTitle` | boolean | Hide the window title bar. | `false` | | `ui.hideTips` | boolean | Hide helpful tips in the UI. | `false` | | `ui.hideBanner` | boolean | Hide the application banner. | `false` | | `ui.hideFooter` | boolean | Hide the footer from the UI. | `false` | | `ui.showMemoryUsage` | boolean | Display memory usage information in the UI. | `false` | | `ui.showLineNumbers` | boolean | Show line numbers in code blocks in the CLI output. | `true` | | `ui.showCitations` | boolean | Show citations for generated text in the chat. | `true` | | `enableWelcomeBack` | boolean | Show welcome back dialog when returning to a project with conversation history. When enabled, Qwen Code will automatically detect if you're returning to a project with a previously generated project summary (`.qwen/PROJECT_SUMMARY.md`) and show a dialog allowing you to continue your previous conversation or start fresh. This feature integrates with the `/summary` command and quit confirmation dialog. | `true` | | `ui.accessibility.enableLoadingPhrases` | boolean | Enable loading phrases (disable for accessibility). | `true` | | `ui.accessibility.screenReader` | boolean | Enables screen reader mode, which adjusts the TUI for better compatibility with screen readers. | `false` | | `ui.customWittyPhrases` | array of strings | A list of custom phrases to display during loading states. When provided, the CLI will cycle through these phrases instead of the default ones. | `[]` | #### ide | Setting | Type | Description | Default | | ------------------ | ------- | ---------------------------------------------------- | ------- | | `ide.enabled` | boolean | Enable IDE integration mode. | `false` | | `ide.hasSeenNudge` | boolean | Whether the user has seen the IDE integration nudge. | `false` | #### privacy | Setting | Type | Description | Default | | -------------------------------- | ------- | -------------------------------------- | ------- | | `privacy.usageStatisticsEnabled` | boolean | Enable collection of usage statistics. | `true` | #### model | Setting | Type | Description | Default | | -------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `model.name` | string | The Qwen model to use for conversations. | `undefined` | | `model.maxSessionTurns` | number | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited. | `-1` | | `model.generationConfig` | object | Advanced overrides passed to the underlying content generator. Supports request controls such as `timeout`, `maxRetries`, `enableCacheControl`, `contextWindowSize` (override model's context window size), `modalities` (override auto-detected input modalities), `customHeaders` (custom HTTP headers for API requests), and `extra_body` (additional body parameters for OpenAI-compatible API requests only), along with fine-tuning knobs under `samplingParams` (for example `temperature`, `top_p`, `max_tokens`). Leave unset to rely on provider defaults. | `undefined` | | `model.chatCompression.contextPercentageThreshold` | number | Sets the threshold for chat history compression as a percentage of the model's total token limit. This is a value between 0 and 1 that applies to both automatic compression and the manual `/compress` command. For example, a value of `0.6` will trigger compression when the chat history exceeds 60% of the token limit. Use `0` to disable compression entirely. | `0.7` | | `model.skipNextSpeakerCheck` | boolean | Skip the next speaker check. | `false` | | `model.skipLoopDetection` | boolean | Disables loop detection checks. Loop detection prevents infinite loops in AI responses but can generate false positives that interrupt legitimate workflows. Enable this option if you experience frequent false positive loop detection interruptions. | `false` | | `model.skipStartupContext` | boolean | Skips sending the startup workspace context (environment summary and acknowledgement) at the beginning of each session. Enable this if you prefer to provide context manually or want to save tokens on startup. | `false` | | `model.enableOpenAILogging` | boolean | Enables logging of OpenAI API calls for debugging and analysis. When enabled, API requests and responses are logged to JSON files. | `false` | | `model.openAILoggingDir` | string | Custom directory path for OpenAI API logs. If not specified, defaults to `logs/openai` in the current working directory. Supports absolute paths, relative paths (resolved from current working directory), and `~` expansion (home directory). | `undefined` | **Example model.generationConfig:** ```json { "model": { "generationConfig": { "timeout": 60000, "contextWindowSize": 128000, "modalities": { "image": true }, "enableCacheControl": true, "customHeaders": { "X-Client-Request-ID": "req-123" }, "extra_body": { "enable_thinking": true }, "samplingParams": { "temperature": 0.2, "top_p": 0.8, "max_tokens": 1024 } } } } ``` **contextWindowSize:** Overrides the default context window size for the selected model. Qwen Code determines the context window using built-in defaults based on model name matching, with a constant fallback value. Use this setting when a provider's effective context limit differs from Qwen Code's default. This value defines the model's assumed maximum context capacity, not a per-request token limit. **modalities:** Overrides the auto-detected input modalities for the selected model. Qwen Code automatically detects supported modalities (image, PDF, audio, video) based on model name pattern matching. Use this setting when the auto-detection is incorrect — for example, to enable `pdf` for a model that supports it but isn't recognized. Format: `{ "image": true, "pdf": true, "audio": true, "video": true }`. Omit a key or set it to `false` for unsupported types. **customHeaders:** Allows you to add custom HTTP headers to all API requests. This is useful for request tracing, monitoring, API gateway routing, or when different models require different headers. If `customHeaders` is defined in `modelProviders[].generationConfig.customHeaders`, it will be used directly; otherwise, headers from `model.generationConfig.customHeaders` will be used. No merging occurs between the two levels. The `extra_body` field allows you to add custom parameters to the request body sent to the API. This is useful for provider-specific options that are not covered by the standard configuration fields. **Note: This field is only supported for OpenAI-compatible providers (`openai`, `qwen-oauth`). It is ignored for Anthropic and Gemini providers.** If `extra_body` is defined in `modelProviders[].generationConfig.extra_body`, it will be used directly; otherwise, values from `model.generationConfig.extra_body` will be used. **model.openAILoggingDir examples:** - `"~/qwen-logs"` - Logs to `~/qwen-logs` directory - `"./custom-logs"` - Logs to `./custom-logs` relative to current directory - `"/tmp/openai-logs"` - Logs to absolute path `/tmp/openai-logs` #### context | Setting | Type | Description | Default | | ------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `context.fileName` | string or array of strings | The name of the context file(s). | `undefined` | | `context.importFormat` | string | The format to use when importing memory. | `undefined` | | `context.includeDirectories` | array | Additional directories to include in the workspace context. Specifies an array of additional absolute or relative paths to include in the workspace context. Missing directories will be skipped with a warning by default. Paths can use `~` to refer to the user's home directory. This setting can be combined with the `--include-directories` command-line flag. | `[]` | | `context.loadFromIncludeDirectories` | boolean | Controls the behavior of the `/memory refresh` command. If set to `true`, `QWEN.md` files should be loaded from all directories that are added. If set to `false`, `QWEN.md` should only be loaded from the current directory. | `false` | | `context.fileFiltering.respectGitIgnore` | boolean | Respect .gitignore files when searching. | `true` | | `context.fileFiltering.respectQwenIgnore` | boolean | Respect .qwenignore files when searching. | `true` | | `context.fileFiltering.enableRecursiveFileSearch` | boolean | Whether to enable searching recursively for filenames under the current tree when completing `@` prefixes in the prompt. | `true` | | `context.fileFiltering.enableFuzzySearch` | boolean | When `true`, enables fuzzy search capabilities when searching for files. Set to `false` to improve performance on projects with a large number of files. | `true` | #### Troubleshooting File Search Performance If you are experiencing performance issues with file searching (e.g., with `@` completions), especially in projects with a very large number of files, here are a few things you can try in order of recommendation: 1. **Use `.qwenignore`:** Create a `.qwenignore` file in your project root to exclude directories that contain a large number of files that you don't need to reference (e.g., build artifacts, logs, `node_modules`). Reducing the total number of files crawled is the most effective way to improve performance. 2. **Disable Fuzzy Search:** If ignoring files is not enough, you can disable fuzzy search by setting `enableFuzzySearch` to `false` in your `settings.json` file. This will use a simpler, non-fuzzy matching algorithm, which can be faster. 3. **Disable Recursive File Search:** As a last resort, you can disable recursive file search entirely by setting `enableRecursiveFileSearch` to `false`. This will be the fastest option as it avoids a recursive crawl of your project. However, it means you will need to type the full path to files when using `@` completions. #### tools | Setting | Type | Description | Default | Notes | | ------------------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tools.sandbox` | boolean or string | Sandbox execution environment (can be a boolean or a path string). | `undefined` | | | `tools.shell.enableInteractiveShell` | boolean | Use `node-pty` for an interactive shell experience. Fallback to `child_process` still applies. | `false` | | | `tools.core` | array of strings | **Deprecated.** Will be removed in next version. Use `permissions.allow` + `permissions.deny` instead. Restricts built-in tools to an allowlist. All tools not in the list are disabled. | `undefined` | | | `tools.exclude` | array of strings | **Deprecated.** Use `permissions.deny` instead. Tool names to exclude from discovery. Automatically migrated to the `permissions` format on first load. | `undefined` | | | `tools.allowed` | array of strings | **Deprecated.** Use `permissions.allow` instead. Tool names that bypass the confirmation dialog. Automatically migrated to the `permissions` format on first load. | `undefined` | | | `tools.approvalMode` | string | Sets the default approval mode for tool usage. | `default` | Possible values: `plan` (analyze only, do not modify files or execute commands), `default` (require approval before file edits or shell commands run), `auto-edit` (automatically approve file edits), `yolo` (automatically approve all tool calls) | | `tools.discoveryCommand` | string | Command to run for tool discovery. | `undefined` | | | `tools.callCommand` | string | Defines a custom shell command for calling a specific tool that was discovered using `tools.discoveryCommand`. The shell command must meet the following criteria: It must take function `name` (exactly as in [function declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)) as first command line argument. It must read function arguments as JSON on `stdin`, analogous to [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall). It must return function output as JSON on `stdout`, analogous to [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse). | `undefined` | | | `tools.useRipgrep` | boolean | Use ripgrep for file content search instead of the fallback implementation. Provides faster search performance. | `true` | | | `tools.useBuiltinRipgrep` | boolean | Use the bundled ripgrep binary. When set to `false`, the system-level `rg` command will be used instead. This setting is only effective when `tools.useRipgrep` is `true`. | `true` | | | `tools.truncateToolOutputThreshold` | number | Truncate tool output if it is larger than this many characters. Applies to Shell, Grep, Glob, ReadFile and ReadManyFiles tools. | `25000` | Requires restart: Yes | | `tools.truncateToolOutputLines` | number | Maximum lines or entries kept when truncating tool output. Applies to Shell, Grep, Glob, ReadFile and ReadManyFiles tools. | `1000` | Requires restart: Yes | > [!note] > > **Migrating from `tools.core` / `tools.exclude` / `tools.allowed`:** These legacy settings are **deprecated** and automatically migrated to the new `permissions` format on first load. Prefer configuring `permissions.allow` / `permissions.deny` directly. Use `/permissions` to manage rules interactively. #### permissions The permissions system provides fine-grained control over which tools can run, which require confirmation, and which are blocked. **Decision priority (highest first): `deny` > `ask` > `allow` > _(default/interactive mode)_** The first matching rule wins. Rules use the format `"ToolName"` or `"ToolName(specifier)"`. | Setting | Type | Description | Default | | ------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- | ----------- | | `permissions.allow` | array of strings | Rules for auto-approved tool calls (no confirmation needed). Merged across all scopes (user + project + system). | `undefined` | | `permissions.ask` | array of strings | Rules for tool calls that always require user confirmation. Takes priority over `allow`. | `undefined` | | `permissions.deny` | array of strings | Rules for blocked tool calls. Highest priority — overrides both `allow` and `ask`. | `undefined` | **Tool name aliases (any of these work in rules):** | Alias | Canonical tool | Notes | | --------------------- | ------------------- | ------------------------- | | `Bash`, `Shell` | `run_shell_command` | | | `Read`, `ReadFile` | `read_file` | Meta-category — see below | | `Edit`, `EditFile` | `edit` | Meta-category — see below | | `Write`, `WriteFile` | `write_file` | | | `Grep`, `SearchFiles` | `grep_search` | | | `Glob`, `FindFiles` | `glob` | | | `ListFiles` | `list_directory` | | | `WebFetch` | `web_fetch` | | | `Agent` | `task` | | | `Skill` | `skill` | | **Meta-categories:** Some rule names automatically cover multiple tools: | Rule name | Tools covered | | --------- | ---------------------------------------------------- | | `Read` | `read_file`, `grep_search`, `glob`, `list_directory` | | `Edit` | `edit`, `write_file` | > [!important] > `Read(/path/**)` matches **all four** read tools (file read, grep, glob, and directory listing). > To restrict only file reading, use `ReadFile(/path/**)` or `read_file(/path/**)`. **Rule syntax examples:** | Rule | Meaning | | ----------------------------- | -------------------------------------------------------------- | | `"Bash"` | All shell commands | | `"Bash(git *)"` | Shell commands starting with `git` (word boundary: NOT `gitk`) | | `"Bash(git push *)"` | Shell commands like `git push origin main` | | `"Bash(npm run *)"` | Any `npm run` script | | `"Read"` | All file read operations (read, grep, glob, list) | | `"Read(./secrets/**)"` | Read any file under `./secrets/` recursively | | `"Edit(/src/**/*.ts)"` | Edit TypeScript files under project root `/src/` | | `"WebFetch(api.example.com)"` | Fetch from `api.example.com` and all its subdomains | | `"mcp__puppeteer"` | All tools from the puppeteer MCP server | **Path pattern prefixes:** | Prefix | Meaning | Example | | ------ | ------------------------------------- | ------------------- | | `//` | Absolute path from filesystem root | `//etc/passwd` | | `~/` | Relative to home directory | `~/Documents/*.pdf` | | `/` | Relative to project root | `/src/**/*.ts` | | `./` | Relative to current working directory | `./secrets/**` | | (none) | Same as `./` | `secrets/**` | **Shell command bypass prevention:** Permission rules for `Read`, `Edit`, and `WebFetch` are also enforced when the agent runs equivalent shell commands. For example, if `Read(./.env)` is in `deny`, the agent cannot bypass it via `cat .env` in a shell command. Supported shell commands include `cat`, `grep`, `curl`, `wget`, `cp`, `mv`, `rm`, `chmod`, and many more. Unknown/safe commands (e.g. `git`) are unaffected by file/network rules. **Migrating from legacy settings:** | Legacy setting | Equivalent `permissions` rule | Notes | | --------------- | ------------------------------- | ------------------------------------------------------------ | | `tools.allowed` | `permissions.allow` | Auto-migrated on first load | | `tools.exclude` | `permissions.deny` | Auto-migrated on first load | | `tools.core` | `permissions.allow` (allowlist) | Auto-migrated; unlisted tools are disabled at registry level | **Example configuration:** ```json { "permissions": { "allow": ["Bash(git *)", "Bash(npm run *)", "Read(//Users/alice/code/**)"], "ask": ["Bash(git push *)", "Edit"], "deny": ["Bash(rm -rf *)", "Read(.env)", "WebFetch(malicious.com)"] } } ``` > [!tip] > Use `/permissions` in the interactive CLI to view, add, and remove rules without editing `settings.json` directly. #### mcp | Setting | Type | Description | Default | | ------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `mcp.serverCommand` | string | Command to start an MCP server. | `undefined` | | `mcp.allowed` | array of strings | An allowlist of MCP servers to allow. Allows you to specify a list of MCP server names that should be made available to the model. This can be used to restrict the set of MCP servers to connect to. Note that this will be ignored if `--allowed-mcp-server-names` is set. | `undefined` | | `mcp.excluded` | array of strings | A denylist of MCP servers to exclude. A server listed in both `mcp.excluded` and `mcp.allowed` is excluded. Note that this will be ignored if `--allowed-mcp-server-names` is set. | `undefined` | > [!note] > > **Security Note for MCP servers:** These settings use simple string matching on MCP server names, which can be modified. If you're a system administrator looking to prevent users from bypassing this, consider configuring the `mcpServers` at the system settings level such that the user will not be able to configure any MCP servers of their own. This should not be used as an airtight security mechanism. #### lsp > [!warning] > **Experimental Feature**: LSP support is currently experimental and disabled by default. Enable it using the `--experimental-lsp` command line flag. Language Server Protocol (LSP) provides code intelligence features like go-to-definition, find references, and diagnostics. LSP server configuration is done through `.lsp.json` files in your project root directory, not through `settings.json`. See the [LSP documentation](../features/lsp) for configuration details and examples. #### security | Setting | Type | Description | Default | | ------------------------------ | ------- | ------------------------------------------------- | ----------- | | `security.folderTrust.enabled` | boolean | Setting to track whether Folder trust is enabled. | `false` | | `security.auth.selectedType` | string | The currently selected authentication type. | `undefined` | | `security.auth.enforcedType` | string | The required auth type (useful for enterprises). | `undefined` | | `security.auth.useExternal` | boolean | Whether to use an external authentication flow. | `undefined` | #### advanced | Setting | Type | Description | Default | | ------------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `advanced.autoConfigureMemory` | boolean | Automatically configure Node.js memory limits. | `false` | | `advanced.dnsResolutionOrder` | string | The DNS resolution order. | `undefined` | | `advanced.excludedEnvVars` | array of strings | Environment variables to exclude from project context. Specifies environment variables that should be excluded from being loaded from project `.env` files. This prevents project-specific environment variables (like `DEBUG=true`) from interfering with the CLI behavior. Variables from `.qwen/.env` files are never excluded. | `["DEBUG","DEBUG_MODE"]` | | `advanced.bugCommand` | object | Configuration for the bug report command. Overrides the default URL for the `/bug` command. Properties: `urlTemplate` (string): A URL that can contain `{title}` and `{info}` placeholders. Example: `"bugCommand": { "urlTemplate": "https://bug.example.com/new?title={title}&info={info}" }` | `undefined` | | `advanced.tavilyApiKey` | string | API key for Tavily web search service. Used to enable the `web_search` tool functionality. | `undefined` | > [!note] > > **Note about advanced.tavilyApiKey:** This is a legacy configuration format. For Qwen OAuth users, DashScope provider is automatically available without any configuration. For other authentication types, configure Tavily or Google providers using the new `webSearch` configuration format. #### mcpServers Configures connections to one or more Model-Context Protocol (MCP) servers for discovering and using custom tools. Qwen Code attempts to connect to each configured MCP server to discover available tools. If multiple MCP servers expose a tool with the same name, the tool names will be prefixed with the server alias you defined in the configuration (e.g., `serverAlias__actualToolName`) to avoid conflicts. Note that the system might strip certain schema properties from MCP tool definitions for compatibility. At least one of `command`, `url`, or `httpUrl` must be provided. If multiple are specified, the order of precedence is `httpUrl`, then `url`, then `command`. | Property | Type | Description | Optional | | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | `mcpServers.
See more about [Approval Mode](../features/approval-mode). | | `--allowed-tools` | | A comma-separated list of tool names that will bypass the confirmation dialog. | Tool names | Example: `qwen --allowed-tools "Shell(git status)"` | | `--telemetry` | | Enables [telemetry](/developers/development/telemetry). | | | | `--telemetry-target` | | Sets the telemetry target. | | See [telemetry](/developers/development/telemetry) for more information. | | `--telemetry-otlp-endpoint` | | Sets the OTLP endpoint for telemetry. | | See [telemetry](../../developers/development/telemetry) for more information. | | `--telemetry-otlp-protocol` | | Sets the OTLP protocol for telemetry (`grpc` or `http`). | | Defaults to `grpc`. See [telemetry](../../developers/development/telemetry) for more information. | | `--telemetry-log-prompts` | | Enables logging of prompts for telemetry. | | See [telemetry](../../developers/development/telemetry) for more information. | | `--checkpointing` | | Enables [checkpointing](../features/checkpointing). | | | | `--acp` | | Enables ACP mode (Agent Client Protocol). Useful for IDE/editor integrations like [Zed](../integration-zed). | | Stable. Replaces the deprecated `--experimental-acp` flag. | | `--experimental-lsp` | | Enables experimental [LSP (Language Server Protocol)](../features/lsp) feature for code intelligence (go-to-definition, find references, diagnostics, etc.). | | Experimental. Requires language servers to be installed. | | `--extensions` | `-e` | Specifies a list of extensions to use for the session. | Extension names | If not provided, all available extensions are used. Use the special term `qwen -e none` to disable all extensions. Example: `qwen -e my-extension -e my-other-extension` | | `--list-extensions` | `-l` | Lists all available extensions and exits. | | | | `--proxy` | | Sets the proxy for the CLI. | Proxy URL | Example: `--proxy http://localhost:7890`. | | `--include-directories` | | Includes additional directories in the workspace for multi-directory support. | Directory paths | Can be specified multiple times or as comma-separated values. 5 directories can be added at maximum. Example: `--include-directories /path/to/project1,/path/to/project2` or `--include-directories /path/to/project1 --include-directories /path/to/project2` | | `--screen-reader` | | Enables screen reader mode, which adjusts the TUI for better compatibility with screen readers. | | | | `--version` | | Displays the version of the CLI. | | | | `--openai-logging` | | Enables logging of OpenAI API calls for debugging and analysis. | | This flag overrides the `enableOpenAILogging` setting in `settings.json`. | | `--openai-logging-dir` | | Sets a custom directory path for OpenAI API logs. | Directory path | This flag overrides the `openAILoggingDir` setting in `settings.json`. Supports absolute paths, relative paths, and `~` expansion. Example: `qwen --openai-logging-dir "~/qwen-logs" --openai-logging` | | `--tavily-api-key` | | Sets the Tavily API key for web search functionality for this session. | API key | Example: `qwen --tavily-api-key tvly-your-api-key-here` | ## Context Files (Hierarchical Instructional Context) While not strictly configuration for the CLI's _behavior_, context files (defaulting to `QWEN.md` but configurable via the `context.fileName` setting) are crucial for configuring the _instructional context_ (also referred to as "memory"). This powerful feature allows you to give project-specific instructions, coding style guides, or any relevant background information to the AI, making its responses more tailored and accurate to your needs. The CLI includes UI elements, such as an indicator in the footer showing the number of loaded context files, to keep you informed about the active context. - **Purpose:** These Markdown files contain instructions, guidelines, or context that you want the Qwen model to be aware of during your interactions. The system is designed to manage this instructional context hierarchically. ### Example Context File Content (e.g. `QWEN.md`) Here's a conceptual example of what a context file at the root of a TypeScript project might contain: ``` # Project: My Awesome TypeScript Library ## General Instructions: - When generating new TypeScript code, please follow the existing coding style. - Ensure all new functions and classes have JSDoc comments. - Prefer functional programming paradigms where appropriate. - All code should be compatible with TypeScript 5.0 and Node.js 20+. ## Coding Style: - Use 2 spaces for indentation. - Interface names should be prefixed with `I` (e.g., `IUserService`). - Private class members should be prefixed with an underscore (`_`). - Always use strict equality (`===` and `!==`). ## Specific Component: `src/api/client.ts` - This file handles all outbound API requests. - When adding new API call functions, ensure they include robust error handling and logging. - Use the existing `fetchWithRetry` utility for all GET requests. ## Regarding Dependencies: - Avoid introducing new external dependencies unless absolutely necessary. - If a new dependency is required, please state the reason. ``` This example demonstrates how you can provide general project context, specific coding conventions, and even notes about particular files or components. The more relevant and precise your context files are, the better the AI can assist you. Project-specific context files are highly encouraged to establish conventions and context. - **Hierarchical Loading and Precedence:** The CLI implements a hierarchical memory system by loading context files (e.g., `QWEN.md`) from several locations. Content from files lower in this list (more specific) typically overrides or supplements content from files higher up (more general). The exact concatenation order and final context can be inspected using the `/memory show` command. The typical loading order is: 1. **Global Context File:** - Location: `~/.qwen/
### Using Your Custom Theme
- Select your custom theme using the `/theme` command in Qwen Code. Your custom theme will appear in the theme selection dialog.
- Or, set it as the default by adding `"theme": "MyCustomTheme"` to the `ui` object in your `settings.json`.
- Custom themes can be set at the user, project, or system level, and follow the same [configuration precedence](../configuration/settings) as other settings.
## Themes Preview
| Dark Theme | Preview | Light Theme | Preview |
| :----------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| ANSI | 
| ANSI Light | 
|
| Atom OneDark | 
| Ayu Light | 
|
| Ayu | 
| Default Light | 
|
| Default | 
| GitHub Light | 
|
| Dracula | 
| Google Code | 
|
| GitHub | 
| Xcode | 
|
================================================
FILE: docs/users/configuration/trusted-folders.md
================================================
# Trusted Folders
The Trusted Folders feature is a security setting that gives you control over which projects can use the full capabilities of the Qwen Code. It prevents potentially malicious code from running by asking you to approve a folder before the CLI loads any project-specific configurations from it.
## Enabling the Feature
The Trusted Folders feature is **disabled by default**. To use it, you must first enable it in your settings.
Add the following to your user `settings.json` file:
```json
{
"security": {
"folderTrust": {
"enabled": true
}
}
}
```
## How It Works: The Trust Dialog
Once the feature is enabled, the first time you run the Qwen Code from a folder, a dialog will automatically appear, prompting you to make a choice:
- **Trust folder**: Grants full trust to the current folder (e.g. `my-project`).
- **Trust parent folder**: Grants trust to the parent directory (e.g. `safe-projects`), which automatically trusts all of its subdirectories as well. This is useful if you keep all your safe projects in one place.
- **Don't trust**: Marks the folder as untrusted. The CLI will operate in a restricted "safe mode."
Your choice is saved in a central file (`~/.qwen/trustedFolders.json`), so you will only be asked once per folder.
## Why Trust Matters: The Impact of an Untrusted Workspace
When a folder is **untrusted**, the Qwen Code runs in a restricted "safe mode" to protect you. In this mode, the following features are disabled:
1. **Workspace Settings are Ignored**: The CLI will **not** load the `.qwen/settings.json` file from the project. This prevents the loading of custom tools and other potentially dangerous configurations.
2. **Environment Variables are Ignored**: The CLI will **not** load any `.env` files from the project.
3. **Extension Management is Restricted**: You **cannot install, update, or uninstall** extensions.
4. **Tool Auto-Acceptance is Disabled**: You will always be prompted before any tool is run, even if you have auto-acceptance enabled globally.
5. **Automatic Memory Loading is Disabled**: The CLI will not automatically load files into context from directories specified in local settings.
Granting trust to a folder unlocks the full functionality of the Qwen Code for that workspace.
## Managing Your Trust Settings
If you need to change a decision or see all your settings, you have a couple of options:
- **Change the Current Folder's Trust**: Run the `/permissions` command from within the CLI. This will bring up the same interactive dialog, allowing you to change the trust level for the current folder.
- **View All Trust Rules**: To see a complete list of all your trusted and untrusted folder rules, you can inspect the contents of the `~/.qwen/trustedFolders.json` file in your home directory.
## The Trust Check Process (Advanced)
For advanced users, it's helpful to know the exact order of operations for how trust is determined:
1. **IDE Trust Signal**: If you are using the [IDE Integration](../ide-integration/ide-integration), the CLI first asks the IDE if the workspace is trusted. The IDE's response takes highest priority.
2. **Local Trust File**: If the IDE is not connected, the CLI checks the central `~/.qwen/trustedFolders.json` file.
================================================
FILE: docs/users/extension/_meta.ts
================================================
export default {
introduction: 'Introduction',
'getting-started-extensions': {
display: 'hidden',
},
'extension-releasing': {
display: 'hidden',
},
};
================================================
FILE: docs/users/extension/extension-releasing.md
================================================
# Extension Releasing
There are two primary ways of releasing extensions to users:
- [Git repository](#releasing-through-a-git-repository)
- [Github Releases](#releasing-through-github-releases)
Git repository releases tend to be the simplest and most flexible approach, while GitHub releases can be more efficient on initial install as they are shipped as single archives instead of requiring a git clone which downloads each file individually. Github releases may also contain platform specific archives if you need to ship platform specific binary files.
## Releasing through a git repository
This is the most flexible and simple option. All you need to do us create a publicly accessible git repo (such as a public github repository) and then users can install your extension using `qwen extensions install • Planning complex changes
• Safe code review | Lowest | | **Default** | ✅ Manual approval required | ✅ Manual approval required | • New/unfamiliar codebases
• Critical systems
• Team collaboration
• Learning and teaching | Low | | **Auto-Edit** | ✅ Auto-approved | ❌ Manual approval required | • Daily development tasks
• Refactoring and code improvements
• Safe automation | Medium | | **YOLO** | ✅ Auto-approved | ✅ Auto-approved | • Trusted personal projects
• Automated scripts/CI/CD
• Batch processing tasks | Highest | ### Quick Reference Guide - **Start in Plan Mode**: Great for understanding before making changes - **Work in Default Mode**: The balanced choice for most development work - **Switch to Auto-Edit**: When you're making lots of safe code changes - **Use YOLO sparingly**: Only for trusted automation in controlled environments > [!tip] > > You can quickly cycle through modes during a session using **Shift+Tab** (or **Tab** on Windows). The terminal status bar shows your current mode, so you always know what permissions Qwen Code has. ## 1. Use Plan Mode for safe code analysis Plan Mode instructs Qwen Code to create a plan by analyzing the codebase with **read-only** operations, perfect for exploring codebases, planning complex changes, or reviewing code safely. ### When to use Plan Mode - **Multi-step implementation**: When your feature requires making edits to many files - **Code exploration**: When you want to research the codebase thoroughly before changing anything - **Interactive development**: When you want to iterate on the direction with Qwen Code ### How to use Plan Mode **Turn on Plan Mode during a session** You can switch into Plan Mode during a session using **Shift+Tab** (or **Tab** on Windows) to cycle through permission modes. If you are in Normal Mode, **Shift+Tab** (or **Tab** on Windows) first switches into `auto-edits` Mode, indicated by `⏵⏵ accept edits on` at the bottom of the terminal. A subsequent **Shift+Tab** (or **Tab** on Windows) will switch into Plan Mode, indicated by `⏸ plan mode`. **Start a new session in Plan Mode** To start a new session in Plan Mode, use the `/approval-mode` then select `plan` ```bash /approval-mode ``` **Run "headless" queries in Plan Mode** You can also run a query in Plan Mode directly with `-p` or `prompt`: ```bash qwen --prompt "What is machine learning?" ``` ### Example: Planning a complex refactor ```bash /approval-mode plan ``` ``` I need to refactor our authentication system to use OAuth2. Create a detailed migration plan. ``` Qwen Code analyzes the current implementation and create a comprehensive plan. Refine with follow-ups: ``` What about backward compatibility? How should we handle database migration? ``` ### Configure Plan Mode as default ```json // .qwen/settings.json { "permissions": { "defaultMode": "plan" } } ``` ## 2. Use Default Mode for Controlled Interaction Default Mode is the standard way to work with Qwen Code. In this mode, you maintain full control over all potentially risky operations - Qwen Code will ask for your approval before making any file changes or executing shell commands. ### When to use Default Mode - **New to a codebase**: When you're exploring an unfamiliar project and want to be extra cautious - **Critical systems**: When working on production code, infrastructure, or sensitive data - **Learning and teaching**: When you want to understand each step Qwen Code is taking - **Team collaboration**: When multiple people are working on the same codebase - **Complex operations**: When the changes involve multiple files or complex logic ### How to use Default Mode **Turn on Default Mode during a session** You can switch into Default Mode during a session using **Shift+Tab** (or **Tab** on Windows) to cycle through permission modes. If you're in any other mode, pressing **Shift+Tab** (or **Tab** on Windows) will eventually cycle back to Default Mode, indicated by the absence of any mode indicator at the bottom of the terminal. **Start a new session in Default Mode** Default Mode is the initial mode when you start Qwen Code. If you've changed modes and want to return to Default Mode, use: ``` /approval-mode default ``` **Run "headless" queries in Default Mode** When running headless commands, Default Mode is the default behavior. You can explicitly specify it with: ``` qwen --prompt "Analyze this code for potential bugs" ``` ### Example: Safely implementing a feature ``` /approval-mode default ``` ``` I need to add user profile pictures to our application. The pictures should be stored in an S3 bucket and the URLs saved in the database. ``` Qwen Code will analyze your codebase and propose a plan. It will then ask for approval before: 1. Creating new files (controllers, models, migrations) 2. Modifying existing files (adding new columns, updating APIs) 3. Running any shell commands (database migrations, dependency installation) You can review each proposed change and approve or reject it individually. ### Configure Default Mode as default ```bash // .qwen/settings.json { "permissions": { "defaultMode": "default" } } ``` ## 3. Auto Edits Mode Auto-Edit Mode instructs Qwen Code to automatically approve file edits while requiring manual approval for shell commands, ideal for accelerating development workflows while maintaining system safety. ### When to use Auto-Accept Edits Mode - **Daily development**: Ideal for most coding tasks - **Safe automation**: Allows AI to modify code while preventing accidental execution of dangerous commands - **Team collaboration**: Use in shared projects to avoid unintended impacts on others ### How to switch to this mode ``` # Switch via command /approval-mode auto-edit # Or use keyboard shortcut Shift+Tab (or Tab on Windows) # Switch from other modes ``` ### Workflow Example 1. You ask Qwen Code to refactor a function 2. AI analyzes the code and proposes changes 3. **Automatically** applies all file changes without confirmation 4. If tests need to be run, it will **request approval** to execute `npm test` ## 4. YOLO Mode - Full Automation YOLO Mode grants Qwen Code the highest permissions, automatically approving all tool calls including file editing and shell commands. ### When to use YOLO Mode - **Automated scripts**: Running predefined automated tasks - **CI/CD pipelines**: Automated execution in controlled environments - **Personal projects**: Rapid iteration in fully trusted environments - **Batch processing**: Tasks requiring multi-step command chains > [!warning] > > **Use YOLO Mode with caution**: AI can execute any command with your terminal permissions. Ensure: > > 1. You trust the current codebase > 2. You understand all actions AI will perform > 3. Important files are backed up or committed to version control ### How to enable YOLO Mode ``` # Temporarily enable (current session only) /approval-mode yolo # Set as project default /approval-mode yolo --project # Set as user global default /approval-mode yolo --user ``` ### Configuration Example ```bash // .qwen/settings.json { "permissions": { "defaultMode": "yolo", "confirmShellCommands": false, "confirmFileEdits": false } } ``` ### Automated Workflow Example ```bash # Fully automated refactoring task qwen --prompt "Run the test suite, fix all failing tests, then commit changes" # Without human intervention, AI will: # 1. Run test commands (auto-approved) # 2. Fix failed test cases (auto-edit files) # 3. Execute git commit (auto-approved) ``` ## Mode Switching & Configuration ### Keyboard Shortcut Switching During a Qwen Code session, use **Shift+Tab** (or **Tab** on Windows) to quickly cycle through the three modes: ``` Default Mode → Auto-Edit Mode → YOLO Mode → Plan Mode → Default Mode ``` ### Persistent Configuration ``` // Project-level: ./.qwen/settings.json // User-level: ~/.qwen/settings.json { "permissions": { "defaultMode": "auto-edit", // or "plan" or "yolo" "confirmShellCommands": true, "confirmFileEdits": true } } ``` ### Mode Usage Recommendations 1. **New to codebase**: Start with **Plan Mode** for safe exploration 2. **Daily development tasks**: Use **Auto-Accept Edits** (default mode), efficient and safe 3. **Automated scripts**: Use **YOLO Mode** in controlled environments for full automation 4. **Complex refactoring**: Use **Plan Mode** first for detailed planning, then switch to appropriate mode for execution ================================================ FILE: docs/users/features/arena.md ================================================ # Agent Arena > Dispatch multiple AI models simultaneously to execute the same task, compare their solutions side-by-side, and select the best result to apply to your workspace. > [!warning] > Agent Arena is experimental. It has [known limitations](#limitations) around display modes and session management. Agent Arena lets you pit multiple AI models against each other on the same task. Each model runs as a fully independent agent in its own isolated Git worktree, so file operations never interfere. When all agents finish, you compare results and select a winner to merge back into your main workspace. Unlike [subagents](/users/features/sub-agents), which delegate focused subtasks within a single session, Arena agents are complete, top-level agent instances — each with its own model, context window, and full tool access. This page covers: - [When to use Agent Arena](#when-to-use-agent-arena) - [Starting an arena session](#start-an-arena-session) - [Interacting with agents](#interact-with-agents), including display modes and navigation - [Comparing results and selecting a winner](#compare-results-and-select-a-winner) - [Best practices](#best-practices) ## When to use Agent Arena Agent Arena is most effective when you want to **evaluate or compare** how different models tackle the same problem. The strongest use cases are: - **Model benchmarking**: Evaluate different models' capabilities on real tasks in your actual codebase, not synthetic benchmarks - **Best-of-N selection**: Get multiple independent solutions and pick the best implementation - **Exploring approaches**: See how different models reason about and solve the same problem — useful for learning and insight - **Risk reduction**: For critical changes, validate that multiple models converge on a similar approach before committing Agent Arena uses significantly more tokens than a single session (each agent has its own context window and model calls). It works best when the value of comparison justifies the cost. For routine tasks where you trust your default model, a single session is more efficient. ## Start an arena session Use the `/arena` slash command to launch a session. Specify the models you want to compete and the task: ``` /arena --models qwen3.5-plus,glm-5,kimi-k2.5 "Refactor the authentication module to use JWT tokens" ``` If you omit `--models`, an interactive model selection dialog appears, letting you pick from your configured providers. ### What happens when you start 1. **Worktree setup**: Qwen Code creates isolated Git worktrees for each agent at `~/.qwen/arena/
(default: 600,000) | Request timeout in milliseconds (default: 600,000ms = 10 minutes) | | `trust` | boolean
(default: false) | When `true`, bypasses all tool call confirmations for this server (default: `false`) | | `includeTools` | array | List of tool names to include from this MCP server. When specified, only the tools listed here will be available from this server (allowlist behavior). If not specified, all tools from the server are enabled by default. | | `excludeTools` | array | List of tool names to exclude from this MCP server. Tools listed here will not be available to the model, even if they are exposed by the server.
Note: `excludeTools` takes precedence over `includeTools` - if a tool is in both lists, it will be excluded. | | `targetAudience` | string | The OAuth Client ID allowlisted on the IAP-protected application you are trying to access. Used with `authProviderType: 'service_account_impersonation'`. | | `targetServiceAccount` | string | The email address of the Google Cloud Service Account to impersonate. Used with `authProviderType: 'service_account_impersonation'`. | ### Manage MCP servers with `qwen mcp` You can always configure MCP servers by manually editing `settings.json`, but the CLI is usually faster. #### Adding a server (`qwen mcp add`) ```bash qwen mcp add [options]
qwen*api_key: *(Optional)\_ The API key for the Qwen API.
- qwen*cli_version: *(Optional, default: `latest`)\_ The version of the Qwen Code CLI to install. Can be "latest", "preview", "nightly", a specific version number, or a git branch, tag, or commit. For more information, see [Qwen Code CLI releases](https://github.com/QwenLM/qwen-code-action/blob/main/docs/releases.md).
- qwen*debug: *(Optional)\_ Enable debug logging and output streaming.
- qwen*model: *(Optional)\_ The model to use with Qwen Code.
- prompt: _(Optional, default: `You are a helpful assistant.`)_ A string passed to the Qwen Code CLI's [`--prompt` argument](https://github.com/QwenLM/qwen-code-action/blob/main/docs/cli/configuration.md#command-line-arguments).
- settings: _(Optional)_ A JSON string written to `.qwen/settings.json` to configure the CLI's _project_ settings.
For more details, see the documentation on [settings files](https://github.com/QwenLM/qwen-code-action/blob/main/docs/cli/configuration.md#settings-files).
- use*qwen_code_assist: *(Optional, default: `false`)\_ Whether to use Code Assist for Qwen Code model access instead of the default Qwen Code API key.
For more information, see the [Qwen Code CLI documentation](https://github.com/QwenLM/qwen-code-action/blob/main/docs/cli/authentication.md).
- use*vertex_ai: *(Optional, default: `false`)\_ Whether to use Vertex AI for Qwen Code model access instead of the default Qwen Code API key.
For more information, see the [Qwen Code CLI documentation](https://github.com/QwenLM/qwen-code-action/blob/main/docs/cli/authentication.md).
- extensions: _(Optional)_ A list of Qwen Code CLI extensions to install.
- upload*artifacts: *(Optional, default: `false`)\_ Whether to upload artifacts to the github action.
- use*pnpm: *(Optional, default: `false`)\_ Whether or not to use pnpm instead of npm to install qwen-code-cli
- workflow*name: *(Optional, default: `${{ github.workflow }}`)\_ The GitHub workflow name, used for telemetry purposes.
### Outputs
- summary: The summarized output from the Qwen Code CLI execution.
- error: The error output from the Qwen Code CLI execution, if any.
### Repository Variables
We recommend setting the following values as repository variables so they can be reused across all workflows. Alternatively, you can set them inline as action inputs in individual workflows or to override repository-level values.
| Name | Description | Type | Required | When Required |
| ------------------ | --------------------------------------------------------- | -------- | -------- | ------------------------- |
| `DEBUG` | Enables debug logging for the Qwen Code CLI. | Variable | No | Never |
| `QWEN_CLI_VERSION` | Controls which version of the Qwen Code CLI is installed. | Variable | No | Pinning the CLI version |
| `APP_ID` | GitHub App ID for custom authentication. | Variable | No | Using a custom GitHub App |
To add a repository variable:
1. Go to your repository's **Settings > Secrets and variables > Actions > New variable**.
2. Enter the variable name and value.
3. Save.
For details about repository variables, refer to the [GitHub documentation on variables][variables].
### Secrets
You can set the following secrets in your repository:
| Name | Description | Required | When Required |
| ----------------- | --------------------------------------------- | -------- | ------------------------------------------ |
| `QWEN_API_KEY` | Your Qwen API key from DashScope. | Yes | Required for all workflows that call Qwen. |
| `APP_PRIVATE_KEY` | Private key for your GitHub App (PEM format). | No | Using a custom GitHub App. |
To add a secret:
1. Go to your repository's **Settings > Secrets and variables >Actions > New repository secret**.
2. Enter the secret name and value.
3. Save.
For more information, refer to the [official GitHub documentation on creating and using encrypted secrets][secrets].
## Authentication
This action requires authentication to the GitHub API and optionally to Qwen Code services.
### GitHub Authentication
You can authenticate with GitHub in two ways:
1. **Default `GITHUB_TOKEN`:** For simpler use cases, the action can use the
default `GITHUB_TOKEN` provided by the workflow.
2. **Custom GitHub App (Recommended):** For the most secure and flexible
authentication, we recommend creating a custom GitHub App.
For detailed setup instructions for both Qwen and GitHub authentication, go to the
[**Authentication documentation**](./configuration/auth).
## Extensions
The Qwen Code CLI can be extended with additional functionality through extensions.
These extensions are installed from source from their GitHub repositories.
For detailed instructions on how to set up and configure extensions, go to the
[Extensions documentation](../developers/extensions/extension).
## Best Practices
To ensure the security, reliability, and efficiency of your automated workflows, we strongly recommend following our best practices. These guidelines cover key areas such as repository security, workflow configuration, and monitoring.
Key recommendations include:
- **Securing Your Repository:** Implementing branch and tag protection, and restricting pull request approvers.
- **Monitoring and Auditing:** Regularly reviewing action logs and enabling OpenTelemetry for deeper insights into performance and behavior.
For a comprehensive guide on securing your repository and workflows, please refer to our [**Best Practices documentation**](./common-workflow).
## Customization
Create a QWEN.md file in the root of your repository to provide
project-specific context and instructions to [Qwen Code CLI](./common-workflow). This is useful for defining
coding conventions, architectural patterns, or other guidelines the model should
follow for a given repository.
## Contributing
Contributions are welcome! Check out the Qwen Code CLI **Contributing Guide** for more details on how to get started.
[secrets]: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
[Qwen Code]: https://github.com/QwenLM/qwen-code
[DashScope]: https://dashscope.console.aliyun.com/apiKey
[Qwen Code CLI]: https://github.com/QwenLM/qwen-code-action/
[variables]: https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables#creating-configuration-variables-for-a-repository
[GitHub CLI]: https://docs.github.com/en/github-cli/github-cli
[QWEN.md]: https://github.com/QwenLM/qwen-code-action/blob/main/docs/cli/configuration.md#context-files-hierarchical-instructional-context
================================================
FILE: docs/users/integration-jetbrains.md
================================================
# JetBrains IDEs
> JetBrains IDEs provide native support for AI coding assistants through the Agent Client Protocol (ACP). This integration allows you to use Qwen Code directly within your JetBrains IDE with real-time code suggestions.
### Features
- **Native agent experience**: Integrated AI assistant panel within your JetBrains IDE
- **Agent Client Protocol**: Full support for ACP enabling advanced IDE interactions
- **Symbol management**: #-mention files to add them to the conversation context
- **Conversation history**: Access to past conversations within the IDE
### Requirements
- JetBrains IDE with ACP support (IntelliJ IDEA, WebStorm, PyCharm, etc.)
- Qwen Code CLI installed
### Installation
#### Install from ACP Registry (Recommend)
1. Install Qwen Code CLI:
```bash
npm install -g @qwen-code/qwen-code
```
2. Open your JetBrains IDE and navigate to AI Chat tool window.
3. Click **Add ACP Agent**, then click **Install**.
For users using JetBrains AI Assistant and/or other ACP agents, click **Install From ACP Registry** in Agents List, then install Qwen Code ACP.
4. The Qwen Code agent should now be available in the AI Assistant panel.
#### Manual Install (for older version of JetBrains IDEs)
1. Install Qwen Code CLI:
```bash
npm install -g @qwen-code/qwen-code
```
2. Open your JetBrains IDE and navigate to AI Chat tool window.
3. Click the 3-dot menu in the upper-right corner and select **Configure ACP Agent** and configure Qwen Code with the following settings:
```json
{
"agent_servers": {
"qwen": {
"command": "/path/to/qwen",
"args": ["--acp"],
"env": {}
}
}
}
```
4. The Qwen Code agent should now be available in the AI Assistant panel
## Troubleshooting
### Agent not appearing
- Run `qwen --version` in terminal to verify installation
- Ensure your JetBrains IDE version supports ACP
- Restart your JetBrains IDE
### Qwen Code not responding
- Check your internet connection
- Verify CLI works by running `qwen` in terminal
- [File an issue on GitHub](https://github.com/qwenlm/qwen-code/issues) if the problem persists
================================================
FILE: docs/users/integration-vscode.md
================================================
# Visual Studio Code
> The VS Code extension (Beta) lets you see Qwen's changes in real-time through a native graphical interface integrated directly into your IDE, making it easier to access and interact with Qwen Code.
### Features - **Native IDE experience**: Dedicated Qwen Code sidebar panel accessed via the Qwen icon - **Auto-accept edits mode**: Automatically apply Qwen's changes as they're made - **File management**: @-mention files or attach files and images using the system file picker - **Conversation history**: Access to past conversations - **Multiple sessions**: Run multiple Qwen Code sessions simultaneously ### Requirements - VS Code 1.85.0 or higher ### Installation Download and install the extension from the [Visual Studio Code Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion). ## Troubleshooting ### Extension not installing - Ensure you have VS Code 1.85.0 or higher - Check that VS Code has permission to install extensions - Try installing directly from the Marketplace website ### Qwen Code not responding - Check your internet connection - Start a new conversation to see if the issue persists - [File an issue on GitHub](https://github.com/qwenlm/qwen-code/issues) if the problem continues ================================================ FILE: docs/users/integration-zed.md ================================================ # Zed Editor > Zed Editor provides native support for AI coding assistants through the Agent Client Protocol (ACP). This integration allows you to use Qwen Code directly within Zed's interface with real-time code suggestions.  ### Features - **Native agent experience**: Integrated AI assistant panel within Zed's interface - **Agent Client Protocol**: Full support for ACP enabling advanced IDE interactions - **File management**: @-mention files to add them to the conversation context - **Conversation history**: Access to past conversations within Zed ### Requirements - Zed Editor (latest version recommended) - Qwen Code CLI installed ### Installation #### Install from ACP Registry (Recommend) 1. Install Qwen Code CLI: ```bash npm install -g @qwen-code/qwen-code ``` 2. Download and install [Zed Editor](https://zed.dev/) 3. In Zed, click the **settings button** in the top right corner, select **"Add agent"**, choose **"Install from Registry"**, find **Qwen Code**, then click **Install**.   #### Manual Install 1. Install Qwen Code CLI: ```bash npm install -g @qwen-code/qwen-code ``` 2. Download and install [Zed Editor](https://zed.dev/) 3. In Zed, click the **settings button** in the top right corner, select **"Add agent"**, choose **"Create a custom agent"**, and add the following configuration: ```json "Qwen Code": { "type": "custom", "command": "qwen", "args": ["--acp"], "env": {} } ```  ## Troubleshooting ### Agent not appearing - Run `qwen --version` in terminal to verify installation - Check that the JSON configuration is valid - Restart Zed Editor ### Qwen Code not responding - Check your internet connection - Verify CLI works by running `qwen` in terminal - [File an issue on GitHub](https://github.com/qwenlm/qwen-code/issues) if the problem persists ================================================ FILE: docs/users/overview.md ================================================ # Qwen Code overview [](https://npm-compare.com/@qwen-code/qwen-code) [](https://www.npmjs.com/package/@qwen-code/qwen-code) > Learn about Qwen Code, Qwen's agentic coding tool that lives in your terminal and helps you turn ideas into code faster than ever before. ## Get started in 30 seconds ### Install Qwen Code: **Linux / macOS** ```sh curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh | bash ``` **Windows (Run as Administrator CMD)** ```sh curl -fsSL -o %TEMP%\install-qwen.bat https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat && %TEMP%\install-qwen.bat ``` > [!note] > > It's recommended to restart your terminal after installation to ensure environment variables take effect. If the installation fails, please refer to [Manual Installation](./quickstart#manual-installation) in the Quickstart guide. ### Start using Qwen Code: ```bash cd your-project qwen ``` Select **Qwen OAuth (Free)** authentication and follow the prompts to log in. Then let's start with understanding your codebase. Try one of these commands: ``` what does this project do? ```  You'll be prompted to log in on first use. That's it! [Continue with Quickstart (5 mins) →](./quickstart) > [!tip] > > See [troubleshooting](./support/troubleshooting) if you hit issues. > [!note] > > **New VS Code Extension (Beta)**: Prefer a graphical interface? Our new **VS Code extension** provides an easy-to-use native IDE experience without requiring terminal familiarity. Simply install from the marketplace and start coding with Qwen Code directly in your sidebar. Download and install the [Qwen Code Companion](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion) now. ## What Qwen Code does for you - **Build features from descriptions**: Tell Qwen Code what you want to build in plain language. It will make a plan, write the code, and ensure it works. - **Debug and fix issues**: Describe a bug or paste an error message. Qwen Code will analyze your codebase, identify the problem, and implement a fix. - **Navigate any codebase**: Ask anything about your team's codebase, and get a thoughtful answer back. Qwen Code maintains awareness of your entire project structure, can find up-to-date information from the web, and with [MCP](./features/mcp) can pull from external datasources like Google Drive, Figma, and Slack. - **Automate tedious tasks**: Fix fiddly lint issues, resolve merge conflicts, and write release notes. Do all this in a single command from your developer machines, or automatically in CI. ## Why developers love Qwen Code - **Works in your terminal**: Not another chat window. Not another IDE. Qwen Code meets you where you already work, with the tools you already love. - **Takes action**: Qwen Code can directly edit files, run commands, and create commits. Need more? [MCP](./features/mcp) lets Qwen Code read your design docs in Google Drive, update your tickets in Jira, or use _your_ custom developer tooling. - **Unix philosophy**: Qwen Code is composable and scriptable. `tail -f app.log | qwen -p "Slack me if you see any anomalies appear in this log stream"` _works_. Your CI can run `qwen -p "If there are new text strings, translate them into French and raise a PR for @lang-fr-team to review"`. ================================================ FILE: docs/users/quickstart.md ================================================ # Quickstart > 👏 Welcome to Qwen Code! This quickstart guide will have you using AI-powered coding assistance in just a few minutes. By the end, you'll understand how to use Qwen Code for common development tasks. ## Before you begin Make sure you have: - A **terminal** or command prompt open - A code project to work with - A [Qwen Code](https://chat.qwen.ai/auth?mode=register) account ## Step 1: Install Qwen Code To install Qwen Code, use one of the following methods: ### Quick Install (Recommended) **Linux / macOS** ```sh curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh | bash ``` **Windows (Run as Administrator CMD)** ```sh curl -fsSL -o %TEMP%\install-qwen.bat https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat && %TEMP%\install-qwen.bat ``` > [!note] > > It's recommended to restart your terminal after installation to ensure environment variables take effect. ### Manual Installation **Prerequisites** Make sure you have Node.js 20 or later installed. Download it from [nodejs.org](https://nodejs.org/en/download). **NPM** ```bash npm install -g @qwen-code/qwen-code@latest ``` **Homebrew (macOS, Linux)** ```bash brew install qwen-code ``` ## Step 2: Log in to your account Qwen Code requires an account to use. When you start an interactive session with the `qwen` command, you'll be prompted to log in: ```bash # You'll be prompted to log in on first use qwen ``` ```bash # Follow the prompts to log in with your account /auth ``` Select `Qwen OAuth`, log in to your account and follow the prompts to confirm. Once logged in, your credentials are stored and you won't need to log in again. > [!note] > > When you first authenticate Qwen Code with your Qwen account, a workspace called ".qwen" is automatically created for you. This workspace provides centralized cost tracking and management for all Qwen Code usage in your organization. > [!tip] > > You can also configure authentication directly from the terminal without starting a session by running `qwen auth`. Use `qwen auth status` to check your current configuration at any time. See the [Authentication](./configuration/auth) page for details. ## Step 3: Start your first session Open your terminal in any project directory and start Qwen Code: ```bash # optiona cd /path/to/your/project # start qwen qwen ``` You'll see the Qwen Code welcome screen with your session information, recent conversations, and latest updates. Type `/help` for available commands. ## Chat with Qwen Code ### Ask your first question Qwen Code will analyze your files and provide a summary. You can also ask more specific questions: ``` explain the folder structure ``` You can also ask Qwen Code about its own capabilities: ``` what can Qwen Code do? ``` > [!note] > > Qwen Code reads your files as needed - you don't have to manually add context. Qwen Code also has access to its own documentation and can answer questions about its features and capabilities. ### Make your first code change Now let's make Qwen Code do some actual coding. Try a simple task: ``` add a hello world function to the main file ``` Qwen Code will: 1. Find the appropriate file 2. Show you the proposed changes 3. Ask for your approval 4. Make the edit > [!note] > > Qwen Code always asks for permission before modifying files. You can approve individual changes or enable "Accept all" mode for a session. ### Use Git with Qwen Code Qwen Code makes Git operations conversational: ``` what files have I changed? ``` ``` commit my changes with a descriptive message ``` You can also prompt for more complex Git operations: ``` create a new branch called feature/quickstart ``` ``` show me the last 5 commits ``` ``` help me resolve merge conflicts ``` ### Fix a bug or add a feature Qwen Code is proficient at debugging and feature implementation. Describe what you want in natural language: ``` add input validation to the user registration form ``` Or fix existing issues: ``` there's a bug where users can submit empty forms - fix it ``` Qwen Code will: - Locate the relevant code - Understand the context - Implement a solution - Run tests if available ### Test out other common workflows There are a number of ways to work with Qwen Code: **Refactor code** ``` refactor the authentication module to use async/await instead of callbacks ``` **Write tests** ``` write unit tests for the calculator functions ``` **Update documentation** ``` update the README with installation instructions ``` **Code review** ``` review my changes and suggest improvements ``` > [!tip] > > **Remember**: Qwen Code is your AI pair programmer. Talk to it like you would a helpful colleague - describe what you want to achieve, and it will help you get there. ## Essential commands Here are the most important commands for daily use: | Command | What it does | Example | | --------------------- | ------------------------------------------------ | ----------------------------- | | `qwen` | start Qwen Code | `qwen` | | `/auth` | Change authentication method (in session) | `/auth` | | `qwen auth` | Configure authentication from the terminal | `qwen auth` | | `qwen auth status` | Check current authentication status | `qwen auth status` | | `/help` | Display help information for available commands | `/help` or `/?` | | `/compress` | Replace chat history with summary to save Tokens | `/compress` | | `/clear` | Clear terminal screen content | `/clear` (shortcut: `Ctrl+L`) | | `/theme` | Change Qwen Code visual theme | `/theme` | | `/language` | View or change language settings | `/language` | | → `ui [language]` | Set UI interface language | `/language ui zh-CN` | | → `output [language]` | Set LLM output language | `/language output Chinese` | | `/quit` | Exit Qwen Code immediately | `/quit` or `/exit` | See the [CLI reference](./features/commands) for a complete list of commands. ## Pro tips for beginners **Be specific with your requests** - Instead of: "fix the bug" - Try: "fix the login bug where users see a blank screen after entering wrong credentials" **Use step-by-step instructions** - Break complex tasks into steps: ``` 1. create a new database table for user profiles 2. create an API endpoint to get and update user profiles 3. build a webpage that allows users to see and edit their information ``` **Let Qwen Code explore first** - Before making changes, let Qwen Code understand your code: ``` analyze the database schema ``` ``` build a dashboard showing products that are most frequently returned by our UK customers ``` **Save time with shortcuts** - Press `?` to see all available keyboard shortcuts - Use Tab for command completion - Press ↑ for command history - Type `/` to see all slash commands ## Getting help - **In Qwen Code**: Type `/help` or ask "how do I..." - **Documentation**: You're here! Browse other guides - **Community**: Join our [GitHub Discussion](https://github.com/QwenLM/qwen-code/discussions) for tips and support ================================================ FILE: docs/users/reference/_meta.ts ================================================ export default { 'keyboard-shortcuts': 'Keyboard Shortcuts', }; ================================================ FILE: docs/users/reference/keyboard-shortcuts.md ================================================ # Qwen Code Keyboard Shortcuts This document lists the available keyboard shortcuts in Qwen Code. ## General | Shortcut | Description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | `Esc` | Close dialogs and suggestions. | | `Ctrl+C` | Cancel the ongoing request and clear the input. Press twice to exit the application. | | `Ctrl+D` | Exit the application if the input is empty. Press twice to confirm. | | `Ctrl+L` | Clear the screen. | | `Ctrl+O` | Toggle the display of the debug console. | | `Ctrl+S` | Allows long responses to print fully, disabling truncation. Use your terminal's scrollback to view the entire output. | | `Ctrl+T` | Toggle the display of tool descriptions. | | `Shift+Tab` (`Tab` on Windows) | Cycle approval modes (`plan` → `default` → `auto-edit` → `yolo`) | ## Input Prompt | Shortcut | Description | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `!` | Toggle shell mode when the input is empty. | | `?` | Toggle keyboard shortcuts display when the input is empty. | | `\` (at end of line) + `Enter` | Insert a newline. | | `Down Arrow` | Navigate down through the input history. | | `Enter` | Submit the current prompt. | | `Meta+Delete` / `Ctrl+Delete` | Delete the word to the right of the cursor. | | `Tab` | Autocomplete the current suggestion if one exists. | | `Up Arrow` | Navigate up through the input history. | | `Ctrl+A` / `Home` | Move the cursor to the beginning of the line. | | `Ctrl+B` / `Left Arrow` | Move the cursor one character to the left. | | `Ctrl+C` | Clear the input prompt | | `Esc` (double press) | Clear the input prompt. | | `Ctrl+D` / `Delete` | Delete the character to the right of the cursor. | | `Ctrl+E` / `End` | Move the cursor to the end of the line. | | `Ctrl+F` / `Right Arrow` | Move the cursor one character to the right. | | `Ctrl+H` / `Backspace` | Delete the character to the left of the cursor. | | `Ctrl+K` | Delete from the cursor to the end of the line. | | `Ctrl+Left Arrow` / `Meta+Left Arrow` / `Meta+B` | Move the cursor one word to the left. | | `Ctrl+N` | Navigate down through the input history. | | `Ctrl+P` | Navigate up through the input history. | | `Ctrl+R` | Reverse search through input/shell history. | | `Ctrl+Y` | Retry the last failed request. | | `Ctrl+Right Arrow` / `Meta+Right Arrow` / `Meta+F` | Move the cursor one word to the right. | | `Ctrl+U` | Delete from the cursor to the beginning of the line. | | `Ctrl+V` (Windows: `Alt+V`) | Paste clipboard content. If the clipboard contains an image, it will be saved and a reference to it will be inserted in the prompt. | | `Ctrl+W` / `Meta+Backspace` / `Ctrl+Backspace` | Delete the word to the left of the cursor. | | `Ctrl+X` / `Meta+Enter` | Open the current input in an external editor. | ## Suggestions | Shortcut | Description | | --------------- | -------------------------------------- | | `Down Arrow` | Navigate down through the suggestions. | | `Tab` / `Enter` | Accept the selected suggestion. | | `Up Arrow` | Navigate up through the suggestions. | ## Radio Button Select | Shortcut | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------- | | `Down Arrow` / `j` | Move selection down. | | `Enter` | Confirm selection. | | `Up Arrow` / `k` | Move selection up. | | `1-9` | Select an item by its number. | | (multi-digit) | For items with numbers greater than 9, press the digits in quick succession to select the corresponding item. | ## IDE Integration | Shortcut | Description | | -------- | --------------------------------- | | `Ctrl+G` | See context CLI received from IDE | ================================================ FILE: docs/users/support/Uninstall.md ================================================ # Uninstall Your uninstall method depends on how you ran the CLI. Follow the instructions for either npx or a global npm installation. ## Method 1: Using npx npx runs packages from a temporary cache without a permanent installation. To "uninstall" the CLI, you must clear this cache, which will remove qwen-code and any other packages previously executed with npx. The npx cache is a directory named `_npx` inside your main npm cache folder. You can find your npm cache path by running `npm config get cache`. **For macOS / Linux** ```bash # The path is typically ~/.npm/_npx rm -rf "$(npm config get cache)/_npx" ``` **For Windows** _Command Prompt_ ```cmd :: The path is typically %LocalAppData%\npm-cache\_npx rmdir /s /q "%LocalAppData%\npm-cache\_npx" ``` _PowerShell_ ```powershell # The path is typically $env:LocalAppData\npm-cache\_npx Remove-Item -Path (Join-Path $env:LocalAppData "npm-cache\_npx") -Recurse -Force ``` ## Method 2: Using npm (Global Install) If you installed the CLI globally (e.g. `npm install -g @qwen-code/qwen-code`), use the `npm uninstall` command with the `-g` flag to remove it. ```bash npm uninstall -g @qwen-code/qwen-code ``` This command completely removes the package from your system. ================================================ FILE: docs/users/support/_meta.ts ================================================ export default { troubleshooting: 'Troubleshooting', 'tos-privacy': 'Terms of Service', Uninstall: 'Uninstall', }; ================================================ FILE: docs/users/support/tos-privacy.md ================================================ # Qwen Code: Terms of Service and Privacy Notice Qwen Code is an open-source AI coding assistant tool maintained by the Qwen Code team. This document outlines the terms of service and privacy policies that apply when using Qwen Code's authentication methods and AI model services. ## How to determine your authentication method Qwen Code supports three authentication methods to access AI models. Your authentication method determines which terms of service and privacy policies apply to your usage: 1. **Qwen OAuth** — Log in with your qwen.ai account (free daily quota) 2. **Alibaba Cloud Coding Plan** — Use an API key from Alibaba Cloud 3. **API Key** — Bring your own API key For each authentication method, different Terms of Service and Privacy Notices may apply depending on the underlying service provider. | Authentication Method | Provider | Terms of Service | Privacy Notice | | :------------------------ | :---------------- | :----------------------------------------------------------------- | :----------------------------------------------------------------- | | Qwen OAuth | Qwen AI | [Qwen Terms of Service](https://qwen.ai/termsservice) | [Qwen Privacy Policy](https://qwen.ai/privacypolicy) | | Alibaba Cloud Coding Plan | Alibaba Cloud | See [details below](#2-if-you-are-using-alibaba-cloud-coding-plan) | See [details below](#2-if-you-are-using-alibaba-cloud-coding-plan) | | API Key | Various Providers | Depends on your chosen API provider (OpenAI, Anthropic, etc.) | Depends on your chosen API provider | ## 1. If you are using Qwen OAuth Authentication When you authenticate using your qwen.ai account, these Terms of Service and Privacy Notice documents apply: - **Terms of Service:** Your use is governed by the [Qwen Terms of Service](https://qwen.ai/termsservice). - **Privacy Notice:** The collection and use of your data is described in the [Qwen Privacy Policy](https://qwen.ai/privacypolicy). For details about authentication setup, quotas, and supported features, see [Authentication Setup](../configuration/settings). ## 2. If you are using Alibaba Cloud Coding Plan When you authenticate using an API key from Alibaba Cloud, the applicable Terms of Service and Privacy Notice from Alibaba Cloud apply. Alibaba Cloud Coding Plan is available in two regions: - **阿里云百炼 (aliyun.com)** — [bailian.console.aliyun.com](https://bailian.console.aliyun.com) - **Alibaba Cloud (alibabacloud.com)** — [bailian.console.alibabacloud.com](https://bailian.console.alibabacloud.com) > [!important] > > When using Alibaba Cloud Coding Plan, you are subject to Alibaba Cloud's terms and privacy policies. Please review their documentation for specific details about data usage, retention, and privacy practices. ## 3. If you are using your own API Key When you authenticate using API keys from other providers, the applicable Terms of Service and Privacy Notice depend on your chosen provider. > [!important] > > When using your own API key, you are subject to the terms and privacy policies of your chosen API provider, not Qwen Code's terms. Please review your provider's documentation for specific details about data usage, retention, and privacy practices. Qwen Code supports various OpenAI-compatible providers. Please refer to your specific provider's terms of service and privacy policy for detailed information. ## Usage Statistics and Telemetry Qwen Code may collect anonymous usage statistics and [telemetry](../../developers/development/telemetry) data to improve the user experience and product quality. This data collection is optional and can be controlled through configuration settings. ### What Data is Collected When enabled, Qwen Code may collect: - Anonymous usage statistics (commands run, performance metrics) - Error reports and crash data - Feature usage patterns ### Data Collection by Authentication Method - **Qwen OAuth:** Usage statistics are governed by Qwen's privacy policy. You can opt-out through Qwen Code's configuration settings. - **Alibaba Cloud Coding Plan:** Usage statistics are governed by Alibaba Cloud's privacy policy. You can opt-out through Qwen Code's configuration settings. - **API Key:** No additional data is collected by Qwen Code beyond what your chosen API provider collects. ## Frequently Asked Questions (FAQ) ### 1. Is my code, including prompts and answers, used to train AI models? Whether your code, including prompts and answers, is used to train AI models depends on your authentication method and the specific AI service provider you use: - **Qwen OAuth**: Data usage is governed by [Qwen's Privacy Policy](https://qwen.ai/privacy). Please refer to their policy for specific details about data collection and model training practices. - **Alibaba Cloud Coding Plan**: Data usage is governed by Alibaba Cloud's privacy policy. Please refer to their policy for specific details about data collection and model training practices. - **API Key**: Data usage depends entirely on your chosen API provider. Each provider has their own data usage policies. Please review the privacy policy and terms of service of your specific provider. **Important**: Qwen Code itself does not use your prompts, code, or responses for model training. Any data usage for training purposes would be governed by the policies of the AI service provider you authenticate with. ### 2. What are Usage Statistics and what does the opt-out control? The **Usage Statistics** setting controls optional data collection by Qwen Code for improving the user experience and product quality. When enabled, Qwen Code may collect: - Anonymous telemetry (commands run, performance metrics, feature usage) - Error reports and crash data - General usage patterns **What is NOT collected by Qwen Code:** - Your code content - Prompts sent to AI models - Responses from AI models - Personal information The Usage Statistics setting only controls data collection by Qwen Code itself. It does not affect what data your chosen AI service provider (Qwen, OpenAI, etc.) may collect according to their own privacy policies. ### 3. How do I switch between authentication methods? You can switch between Qwen OAuth, Alibaba Cloud Coding Plan, and your own API key at any time: 1. **During startup**: Choose your preferred authentication method when prompted 2. **Within the CLI**: Use the `/auth` command to reconfigure your authentication method 3. **Environment variables**: Set up `.env` files for automatic API key authentication For detailed instructions, see the [Authentication Setup](../configuration/settings#environment-variables-for-api-access) documentation. ================================================ FILE: docs/users/support/troubleshooting.md ================================================ # Troubleshooting This guide provides solutions to common issues and debugging tips, including topics on: - Authentication or login errors - Frequently asked questions (FAQs) - Debugging tips - Existing GitHub Issues similar to yours or creating new Issues ## Authentication or login errors - **Error: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, `UNABLE_TO_VERIFY_LEAF_SIGNATURE`, or `unable to get local issuer certificate`** - **Cause:** You may be on a corporate network with a firewall that intercepts and inspects SSL/TLS traffic. This often requires a custom root CA certificate to be trusted by Node.js. - **Solution:** Set the `NODE_EXTRA_CA_CERTS` environment variable to the absolute path of your corporate root CA certificate file. - Example: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` - **Error: `Device authorization flow failed: fetch failed`** - **Cause:** Node.js could not reach Qwen OAuth endpoints (often a proxy or SSL/TLS trust issue). When available, Qwen Code will also print the underlying error cause (for example: `UNABLE_TO_VERIFY_LEAF_SIGNATURE`). - **Solution:** - Confirm you can access `https://chat.qwen.ai` from the same machine/network. - If you are behind a proxy, set it via `qwen --proxy
QWEN
Qwen Code Export
".join(prompt_links) duration = "N/A" if run.get("started_at") and run.get("ended_at"): try: start = datetime.fromisoformat(run["started_at"]) end = datetime.fromisoformat(run["ended_at"]) duration = f"{(end - start).total_seconds():.1f}s" except: pass error_msg = f'
{html.escape(run["error_message"])}
' if run.get("error_message") else ""
rows.append(f"""
{run["run_id"]}Qwen Runner Execution Report
Total
{total}
Succeeded
{succeeded}
Failed
{failed}
Running
{running}
| ID | Task | Model | Status | Duration | Logs & Artifacts | Prompts | Error |
|---|
Updated at: {data["updated_at"]}
"""
async with aiofiles.open(html_file, 'w') as f:
await f.write(html_content)
def get_state(self) -> ExecutionState:
"""Get current execution state."""
runs = list(self._runs.values())
completed = sum(1 for r in runs if r.status in (RunStatus.SUCCEEDED, RunStatus.FAILED))
succeeded = sum(1 for r in runs if r.status == RunStatus.SUCCEEDED)
failed = sum(1 for r in runs if r.status == RunStatus.FAILED)
return ExecutionState(
runs=runs,
total=len(runs),
completed=completed,
succeeded=succeeded,
failed=failed,
)
def get_active_runs(self) -> List[RunRecord]:
"""Get currently active runs."""
active_statuses = {RunStatus.PREPARING, RunStatus.RUNNING}
return [r for r in self._runs.values() if r.status in active_statuses]
class ProgressDisplay:
"""Rich-based progress display."""
def __init__(self, console: Console):
self.console = console
self.live: Optional[Live] = None
def start(self) -> None:
"""Start the live display."""
self.live = Live(auto_refresh=True, console=self.console)
self.live.start()
def stop(self) -> None:
"""Stop the live display."""
if self.live:
self.live.stop()
def update(self, state: ExecutionState) -> None:
"""Update the display with current state."""
if not self.live:
return
# Summary panel
summary = Table.grid(expand=True)
summary.add_column()
summary.add_column()
summary.add_row(
f"[bold]Total:[/bold] {state.total}",
f"[bold]Completed:[/bold] {state.completed}/{state.total}"
)
summary.add_row(
f"[green bold]Succeeded:[/green bold] {state.succeeded}",
f"[red bold]Failed:[/red bold] {state.failed}"
)
# Active runs table
active_runs = [r for r in state.runs if r.status not in (RunStatus.SUCCEEDED, RunStatus.FAILED, RunStatus.QUEUED)]
runs_table = Table(
title="Active Runs",
show_header=True,
header_style="bold magenta",
expand=True,
)
runs_table.add_column("Task", style="cyan")
runs_table.add_column("Model", style="green")
runs_table.add_column("Status", style="yellow")
runs_table.add_column("Started", style="dim")
for run in active_runs[:10]: # Show up to 10 active runs
started = run.started_at or "N/A"
if len(started) > 19:
started = started[11:19] # Extract time portion
runs_table.add_row(
run.task_name[:30],
run.model[:25],
run.status.value,
started,
)
# Recent completed runs
completed_runs = sorted(
[r for r in state.runs if r.status in (RunStatus.SUCCEEDED, RunStatus.FAILED)],
key=lambda r: r.ended_at or "",
reverse=True,
)[:5]
completed_table = Table(
title="Recently Completed",
show_header=True,
header_style="bold blue",
expand=True,
)
completed_table.add_column("Task", style="cyan")
completed_table.add_column("Model", style="green")
completed_table.add_column("Status", style="bold")
completed_table.add_column("Duration", style="dim")
for run in completed_runs:
status_color = "green" if run.status == RunStatus.SUCCEEDED else "red"
duration = "N/A"
if run.started_at and run.ended_at:
try:
start = datetime.fromisoformat(run.started_at)
end = datetime.fromisoformat(run.ended_at)
duration_sec = (end - start).total_seconds()
duration = f"{duration_sec:.1f}s"
except:
pass
completed_table.add_row(
run.task_name[:30],
run.model[:25],
f"[{status_color}]{run.status.value}[/{status_color}]",
duration,
)
# Combine everything
layout = Table.grid(expand=True)
layout.add_column()
layout.add_row(Panel(summary, title="Execution Summary", border_style="blue"))
layout.add_row(runs_table)
if completed_runs:
layout.add_row(completed_table)
self.live.update(layout)
def show_final_summary(self, state: ExecutionState) -> None:
"""Show final execution summary."""
self.console.print()
self.console.print(Panel(
f"[bold green]Execution Complete![/bold green]\n\n"
f"Total Runs: {state.total}\n"
f"Succeeded: [green]{state.succeeded}[/green]\n"
f"Failed: [red]{state.failed}[/red]\n"
f"Success Rate: {(state.succeeded / state.total * 100):.1f}%",
title="Final Results",
border_style="green" if state.failed == 0 else "yellow",
))
class QwenRunner:
"""Executes the Qwen CLI for a specific task and model."""
def __init__(self, config: RunConfig, console: Console):
self.config = config
self.console = console
async def run(
self,
run: RunRecord,
worktree_dir: Path,
output_dir: Path,
) -> None:
"""Execute the Qwen CLI for each prompt sequentially."""
output_dir.mkdir(parents=True, exist_ok=True)
run.output_dir = str(output_dir)
# Get the task and its prompts
task = next((t for t in self.config.tasks if t.id == run.task_id), None)
if not task or not task.prompts:
raise ValueError(f"No prompts found for task {run.task_id}")
# Setup logs directory
run_logs_dir = (output_dir / "openai-logs").resolve()
run_logs_dir.mkdir(parents=True, exist_ok=True)
run.logs_dir = str(run_logs_dir)
# Create outputs subdirectory for cleaner structure
outputs_subdir = output_dir / "outputs"
outputs_subdir.mkdir(parents=True, exist_ok=True)
# Run each prompt sequentially
for prompt_index, prompt_text in enumerate(task.prompts, start=1):
self.console.print(f"[blue]Executing prompt {prompt_index}/{len(task.prompts)}...[/blue]")
# Build command for this prompt
cmd = self._build_command(run, prompt_text, prompt_index > 1)
self.console.print(f"[dim]Command: {' '.join(cmd)}[/dim]")
# Prepare output files for this prompt
stdout_file = outputs_subdir / f"stdout-{prompt_index}.txt"
stderr_file = outputs_subdir / f"stderr-{prompt_index}.txt"
# Run the CLI
env = os.environ.copy()
worktree_dir_resolved = worktree_dir.resolve()
env["QWEN_CODE_ROOT"] = str(worktree_dir_resolved)
proc = await asyncio.create_subprocess_exec(
*cmd,
cwd=worktree_dir_resolved,
stdout=asyncio.subprocess.PIPE,
stderr=asyncio.subprocess.PIPE,
env=env,
)
# Capture output
async def read_stream(stream, file_path):
async with aiofiles.open(file_path, 'w') as f:
while True:
line = await stream.readline()
if not line:
break
decoded = line.decode()
await f.write(decoded)
await f.flush()
await asyncio.gather(
read_stream(proc.stdout, stdout_file),
read_stream(proc.stderr, stderr_file),
)
returncode = await proc.wait()
# Record result for this prompt
prompt_result = PromptResult(
prompt_index=prompt_index,
prompt_text=prompt_text,
stdout_file=str(stdout_file),
stderr_file=str(stderr_file),
exit_code=returncode,
status="succeeded" if returncode == 0 else "failed",
)
run.prompt_results.append(prompt_result)
# Stop on failure
if returncode != 0:
run.exit_code = returncode
raise RuntimeError(f"Prompt {prompt_index} failed with exit code {returncode}")
# All prompts succeeded
run.exit_code = 0
# Set legacy stdout/stderr files to first prompt's files for backwards compatibility
if run.prompt_results:
run.stdout_file = run.prompt_results[0].stdout_file
run.stderr_file = run.prompt_results[0].stderr_file
def _build_command(self, run: RunRecord, prompt_text: str, use_continue: bool = False) -> List[str]:
"""Build the qwen CLI command for a single prompt."""
cmd = ["qwen"]
# Add model
cmd.extend(["--model", run.model])
# Add auth-type when model uses non-OpenAI protocol (e.g. anthropic for glm-4.7)
if run.auth_type:
cmd.extend(["--auth-type", run.auth_type])
# Add yolo if enabled
if self.config.yolo:
cmd.append("--yolo")
# Always enable OpenAI logging to run-specific logs directory
cmd.append("--openai-logging")
cmd.extend(["--openai-logging-dir", run.logs_dir])
# Add --continue flag for follow-up prompts (to pick up chat history)
if use_continue:
cmd.append("--continue")
# Add the prompt
cmd.extend(["--prompt", prompt_text])
return cmd
def generate_run_matrix(config: RunConfig) -> List[RunRecord]:
"""Generate all task × model combinations."""
runs = []
for task in config.tasks:
for model in config.models:
runs.append(RunRecord(
run_id=str(uuid.uuid4())[:8],
task_id=task.id,
task_name=task.name,
model=model.name,
status=RunStatus.QUEUED,
auth_type=model.auth_type,
))
return runs
def _parse_models(data_models: List[Any]) -> List[ModelSpec]:
"""Parse models: string or {name, auth_type/authType}; returns list of ModelSpec."""
specs: List[ModelSpec] = []
for item in data_models or []:
if isinstance(item, str):
name, auth = item, None
elif isinstance(item, dict) and item.get("name"):
name = item["name"]
auth = item.get("auth_type") or item.get("authType")
else:
continue
specs.append(ModelSpec(name=name, auth_type=auth))
return specs
def load_config(config_path: Path) -> RunConfig:
"""Load configuration from JSON file."""
with open(config_path, 'r') as f:
data = json.load(f)
tasks = [Task(**t) for t in data.get("tasks", [])]
models = _parse_models(data.get("models", []))
return RunConfig(
tasks=tasks,
models=models,
concurrency=data.get("concurrency", 4),
yolo=data.get("yolo", True),
source_repo=Path(data.get("source_repo", ".")).resolve(),
worktree_base=Path(data.get("worktree_base", "~/.qwen/worktrees")).expanduser(),
outputs_dir=Path(data.get("outputs_dir", "./outputs")),
results_file=Path(data.get("results_file", "./results.json")),
branch=data.get("branch"),
keep_worktree=data.get("keep_worktree", False),
)
async def execute_single_run(
run: RunRecord,
config: RunConfig,
tracker: StatusTracker,
worktree_manager: GitWorktreeManager,
qwen_runner: QwenRunner,
console: Console,
) -> None:
"""Execute a single run with proper cleanup."""
worktree_dir = None
try:
# Step 1: Create worktree
await tracker.update_status(run.run_id, RunStatus.PREPARING)
worktree_dir = config.worktree_base / f"run-{run.run_id}"
await worktree_manager.create(config.source_repo, worktree_dir, config.branch)
run.worktree_path = str(worktree_dir)
run.started_at = datetime.now().isoformat()
# Step 2: Run CLI
await tracker.update_status(run.run_id, RunStatus.RUNNING)
output_dir = config.outputs_dir / run.run_id
await qwen_runner.run(run, worktree_dir, output_dir)
# Step 3: Success
run.ended_at = datetime.now().isoformat()
await tracker.update_status(
run.run_id,
RunStatus.SUCCEEDED,
exit_code=run.exit_code,
ended_at=run.ended_at,
)
console.print(f"[green]✓[/green] {run.task_name} / {run.model}")
except Exception as e:
run.ended_at = datetime.now().isoformat()
await tracker.update_status(
run.run_id,
RunStatus.FAILED,
error_message=str(e),
ended_at=run.ended_at,
)
console.print(f"[red]✗[/red] {run.task_name} / {run.model}: {e}")
finally:
# Step 4: Capture git diff (before cleanup)
output_dir = config.outputs_dir / run.run_id
output_dir.mkdir(parents=True, exist_ok=True)
if worktree_dir and worktree_dir.exists():
try:
diff_content = await worktree_manager.get_diff(worktree_dir)
if diff_content.strip():
diff_file = output_dir / "diff.patch"
async with aiofiles.open(diff_file, 'w') as f:
await f.write(diff_content)
run.diff_file = str(diff_file)
console.print(f"[dim]Diff saved to {diff_file}[/dim]")
except Exception as e:
console.print(f"[yellow]Warning: Failed to capture diff: {e}[/yellow]")
# Step 5: Collect session log (before cleanup)
if worktree_dir:
try:
result = await worktree_manager.collect_session_log(worktree_dir, output_dir)
if result:
session_log, session_id, session_html = result
run.session_log_file = str(session_log)
run.session_html_file = str(session_html)
run.session_id = session_id
console.print(f"[dim]Session log saved: {session_log.name} (ID: {session_id})[/dim]")
except Exception as e:
console.print(f"[yellow]Warning: Failed to collect session log: {e}[/yellow]")
# Update tracker with all captured files
await tracker.update_status(
run.run_id,
run.status,
diff_file=run.diff_file,
session_log_file=run.session_log_file,
session_html_file=run.session_html_file,
session_id=run.session_id,
)
# Step 7: Cleanup
if worktree_dir:
if config.keep_worktree:
console.print(f"[dim]Keeping worktree: {worktree_dir}[/dim]")
else:
await worktree_manager.remove(worktree_dir)
async def run_all(config: RunConfig, console: Console) -> ExecutionState:
"""Run all task/model combinations concurrently."""
# Setup directories
config.worktree_base.mkdir(parents=True, exist_ok=True)
config.outputs_dir.mkdir(parents=True, exist_ok=True)
# Generate all runs
runs = generate_run_matrix(config)
console.print(f"[bold]Generated {len(runs)} runs:[/bold] {len(config.tasks)} tasks × {len(config.models)} models")
# Initialize components
tracker = StatusTracker(config.results_file, console)
await tracker.initialize(runs)
worktree_manager = GitWorktreeManager(console, config.source_repo)
await worktree_manager.ensure_git_repo()
qwen_runner = QwenRunner(config, console)
display = ProgressDisplay(console)
# Start progress display
display.start()
# Progress update task
stop_event = asyncio.Event()
async def update_progress():
while not stop_event.is_set():
state = tracker.get_state()
display.update(state)
if state.completed >= state.total:
stop_event.set()
break
try:
await asyncio.wait_for(stop_event.wait(), timeout=0.5)
except asyncio.TimeoutError:
continue
# Execute runs with semaphore-controlled concurrency
semaphore = asyncio.Semaphore(config.concurrency)
async def execute_with_limit(run: RunRecord):
async with semaphore:
await execute_single_run(
run, config, tracker, worktree_manager, qwen_runner, console
)
# Run everything
try:
await asyncio.gather(
update_progress(),
asyncio.gather(*[execute_with_limit(r) for r in runs]),
)
finally:
stop_event.set()
display.stop()
# Show final summary
final_state = tracker.get_state()
display.show_final_summary(final_state)
return final_state
def main():
parser = argparse.ArgumentParser(
description="Qwen Concurrent Runner - Execute multiple CLI tasks across models"
)
parser.add_argument(
"config",
type=Path,
help="Path to configuration JSON file",
)
parser.add_argument(
"--version",
action="version",
version="%(prog)s 1.0.0",
)
args = parser.parse_args()
if not args.config.exists():
print(f"Error: Config file not found: {args.config}", file=sys.stderr)
sys.exit(1)
console = Console()
config = load_config(args.config)
try:
final_state = asyncio.run(run_all(config, console))
sys.exit(0 if final_state.failed == 0 else 1)
except KeyboardInterrupt:
console.print("\n[yellow]Interrupted by user[/yellow]")
sys.exit(130)
except Exception as e:
console.print(f"\n[red]Fatal error: {e}[/red]")
sys.exit(1)
if __name__ == "__main__":
main()
================================================
FILE: integration-tests/context-compress-interactive.test.ts
================================================
/**
* @license
* Copyright 2025 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import { expect, describe, it, beforeEach, afterEach } from 'vitest';
import { TestRig, type } from './test-helper.js';
describe('Interactive Mode', () => {
let rig: TestRig;
beforeEach(() => {
rig = new TestRig();
});
afterEach(async () => {
await rig.cleanup();
});
it.skipIf(process.platform === 'win32')(
'should trigger chat compression with /compress command',
async () => {
await rig.setup('interactive-compress-test', {
settings: {
security: {
auth: {
selectedType: 'openai',
},
},
},
});
const { ptyProcess } = rig.runInteractive();
let fullOutput = '';
ptyProcess.onData((data) => (fullOutput += data));
// Wait for the app to be ready
const isReady = await rig.waitForText('Type your message', 15000);
expect(
isReady,
'CLI did not start up in interactive mode correctly',
).toBe(true);
const longPrompt =
'Dont do anything except returning a 1000 token long paragragh with the