Introduction to Qwen

Qwen is an AI coding companion built by Alibaba Group. It lives in your terminal, understands your codebase, and writes code that respects your conventions. Think of it as a senior engineer who never sleeps, never gets tired, and always reads the docs first.

Installation

Qwen Code can be installed via npm:

npm install -g qwen-code

Or using the install script:

curl -fsSL https://get.qwen.ai | bash

Requirements

Quick Start

Navigate to any project directory and start Qwen:

cd your-project
qwen

That's it. Qwen will read your project structure, understand your conventions, and be ready to help.

Your First Prompt

# Just tell Qwen what you need:
"Fix the authentication bug in src/auth.py"
"Add unit tests for the user service"
"Refactor this function to use async/await"
"Explain what this codebase does"

Your First Conversation

Here's what a typical Qwen session looks like:

You: "Add input validation to the signup form"

Qwen: Let me check the current signup form structure...
  → Reading src/components/SignupForm.tsx
  → Checking existing validation patterns in the codebase

  I see the project uses Zod for validation. I'll add validation
  following the same pattern used in LoginForm.tsx.

  [Writes code, runs tests, reports results]

  ✅ All 47 tests passing. Validation added for:
  - Email format (regex)
  - Password strength (min 8 chars, 1 number, 1 special)
  - Username (3-20 chars, alphanumeric)

You: "Perfect, thanks"

Core Philosophy

Qwen operates on five core principles:

1. Conventions First: Always match existing project style, patterns, and idioms.
2. Investigate Before Acting: Read surrounding code, tests, and config before making changes.
3. Minimal Changes: Only modify what's asked. No scope creep, no premature abstractions.
4. Verify Everything: Run tests, check builds, confirm results. Never claim success without proof.
5. Honest & Direct: If something fails, say so. If you can't help, explain why.

Convention Awareness

Before writing any code, Qwen:

• Reads the project's package.json, Cargo.toml, pyproject.toml, or equivalent
• Analyzes existing code style: naming conventions, import patterns, file structure
• Checks for linter configs: .eslintrc, .prettierrc, ruff.toml
• Reads README.md, CONTRIBUTING.md, and any project documentation
• Studies neighboring files to match the exact coding patterns in use

Safety & Verification

Qwen treats your codebase with extreme care:

What Qwen will do freely:

• Read any file in your project
• Edit files within your project directory
• Run tests and build commands
• Create new files following project patterns

What Qwen will ask about first:

• Destructive operations (deleting files, dropping tables)
• Actions outside your project directory
• Pushing to remote repositories
• Modifying system configuration
• Sending messages or making API calls

Context Awareness

Qwen builds a rich understanding of your project:

Project Context Includes:
├── Directory structure & file tree
├── Package dependencies & versions
├── Build scripts & CI/CD config
├── Existing code patterns & architecture
├── Test framework & coverage
├── Linting & formatting rules
├── Git history & recent changes
└── Any .qwen/ or QWEN.md configuration

Code Generation

When generating code, Qwen follows these rules:

1. Read existing similar code first
2. Match the project's style exactly
3. Only add what's needed — no extras
4. Include tests for new functionality
5. Run linters and type checkers after writing

Example: Adding a New Endpoint

You: "Add a GET /api/users/:id endpoint"

Qwen will:
1. Read existing route files to match patterns
2. Check the database schema for user fields
3. Look at existing controllers for the style
4. Write the endpoint matching all conventions
5. Add validation matching existing patterns
6. Write tests matching the test framework
7. Run the test suite to verify
8. Run linting to ensure style compliance

File Operations

Qwen uses dedicated tools for all file operations:

Debugging

When debugging, Qwen follows a systematic approach:

1. Reproduce: Read the error message, stack trace, or symptoms
2. Locate: Search for the relevant code, trace the call chain
3. Understand: Read surrounding context, check git history
4. Fix: Apply the minimal change that resolves the root cause
5. Verify: Run tests, confirm the fix works
6. Report: Explain what was wrong and how it was fixed

Refactoring

Qwen refactors with surgical precision:

• Never changes behavior — only structure
• Runs tests before and after to confirm equivalence
• Respects the project's existing abstractions
• Only refactors what's asked for — no drive-by improvements

Architecture Design

When designing new systems or features, Qwen:

• Understands existing architecture patterns
• Proposes designs that fit the current system
• Considers scalability, maintainability, and testability
• Explains trade-offs clearly

Multi-File Editing

Qwen can orchestrate changes across multiple files in a single task:

You: "Add a new UserSettings feature with full CRUD"

Qwen will coordinate:
  → models/UserSettings.ts     (data model)
  → routes/userSettings.ts     (API routes)
  → controllers/userSettings.ts (business logic)
  → tests/userSettings.test.ts (test suite)
  → migrations/004_user_settings.sql (database)
  → types/UserSettings.d.ts    (type definitions)

Testing & Verification

Qwen verifies everything it builds:

• Identifies the project's test framework (Jest, pytest, go test, etc.)
• Runs the full test suite after changes
• Checks build outputs for errors
• Runs linters and type checkers
• Reports actual results — never fabricates success

Subagent Delegation

For complex tasks, Qwen can spawn specialized subagents:

• Explore Agent: Deep codebase exploration and research
• General-purpose Agent: Multi-step research and analysis
• Statusline Agent: Configuration helpers

Memory System

Qwen maintains persistent memory across sessions:

• User Memory: Your preferences, role, expertise level
• Project Memory: Ongoing work, goals, and context
• Feedback Memory: Corrections and validated approaches
• Reference Memory: External resources and systems

Tool Integration

Qwen integrates with your development environment through dedicated tools:

Available Tools:
├── File System: read, write, edit, search, glob
├── Shell: run_shell_command (for git, npm, etc.)
├── Search: grep_search, glob patterns
├── Notebook: Jupyter notebook editing
├── Task Management: todo tracking
├── Subagents: delegated work
├── MCP: Model Context Protocol servers
└── Custom: project-specific tools

Commands Reference

Configuration

Configure Qwen through project files:

# .qwen/settings.json
{
  "approvalMode": "default",
  "outputLanguage": "English",
  "customInstructions": "Always prefer TypeScript over JavaScript"
}

# QWEN.md (project-level instructions)
# Add custom instructions for this project

# AGENTS.md (agent-level configuration)
# Configure subagent behavior

Troubleshooting

Qwen is running slowly

Use /stuck to diagnose performance issues. Common causes:

• Large project with many files — Qwen is building context
• Network latency to the API endpoint
• Complex multi-file operations in progress

Qwen doesn't understand my project

Add a QWEN.md file to your project root with project-specific instructions. Qwen will read it automatically.

Tests aren't running

Make sure your test command is in package.json scripts, or tell Qwen explicitly how to run tests.