How to Contribute to Qwen Code and Set Up the Development Environment

To contribute to Qwen Code, clone the monorepo, install dependencies with Node 20.19.0, run npm run build to compile the workspace packages in dependency order, and execute npm run preflight to verify code quality before submitting a pull request.

Qwen Code is a TypeScript-based, terminal-first AI agent distributed as a CLI tool and SDK packages. The repository uses an npm workspace monorepo structure where packages/core contains the agent logic, packages/cli houses the command-line interface, and packages/sdk-typescript provides the extension SDK. Understanding how to build and test these interconnected packages is essential for anyone looking to contribute to Qwen Code effectively.

Prerequisites for Contributing to Qwen Code

Node.js Version Requirements

Development requires Node 20.19.0 exactly, which you should manage using nvm. Production deployments can run any Node version ≥ 20, but the build system and test suite are validated against 20.19.0 to ensure reproducible builds across contributor environments.

Git Configuration

You need Git installed to clone the repository and follow the pull request workflow. Fork the repository on GitHub before cloning if you plan to submit changes.

Clone and Install Dependencies

Start by cloning the repository and installing workspace dependencies. The npm install command at the root automatically handles the monorepo structure.

# Clone the repository (or your fork)

git clone https://github.com/QwenLM/qwen-code.git
cd qwen-code

# Install dependencies for all workspaces

npm install

If node_modules is missing, the build script at scripts/build.js automatically runs npm install before compilation.

Build the Monorepo

Compile the TypeScript source across all packages in the correct dependency order. The build orchestrator at scripts/build.js handles the sequence automatically.

# Build all packages in dependency order

npm run build

The build process follows this specific sequence as defined in scripts/build.js (lines 44-49): test-utils → core → cli → webui → SDK → VS Code companion. This ensures that downstream packages have access to compiled dependencies.

Building the Sandbox Container

If you need the sandbox container for safe code execution, set the BUILD_SANDBOX environment variable before building:

BUILD_SANDBOX=1 npm run build

This triggers scripts/build_sandbox.js to construct the containerized execution environment used by the agent.

Run the CLI from Source

After building, you can launch the interactive terminal UI or run headless commands directly from the source.

# Launch the interactive Qwen Code UI

npm start

# Or run headless mode directly

qwen -p "Explain this file"

The CLI entry point resides in packages/cli and compiles to dist/index.js. Running npm start executes this compiled entry point without requiring a global install.

Testing and Code Quality

Run Unit Tests

Execute the test suite across core and CLI packages to verify functionality:

npm run test

Run Preflight Checks

Before committing, run the full preflight suite that mimics CI validation:

npm run preflight

This command runs ESLint, Prettier formatting checks, and all test suites as mandated by CONTRIBUTING.md (lines 39-42). Passing this check locally prevents CI failures on your pull request.

Pre-commit Hooks

The repository includes a pre-commit hook that runs npm run preflight automatically to prevent broken commits. Install it manually after cloning:

echo "

# Run npm build and check for errors

if ! npm run preflight; then
  echo \"npm build failed. Commit aborted.\"
  exit 1
fi
" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

This hook ensures that only code passing linting and tests enters the repository history.

Submitting Your Contribution

Commit Message Convention

Follow Conventional Commits format to enable automated changelog generation:

git commit -m "feat(cli): add --json output flag"
git commit -m "fix(core): resolve session timeout issue"

Valid types include feat, fix, docs, style, refactor, test, and chore.

Pull Request Workflow

1. Link your PR to an existing GitHub issue or create one first describing the bug or feature.
2. Keep changes atomic—submit single bug fixes or focused features rather than broad refactors.
3. Ensure CI passes—GitHub Actions runs npm run preflight on every PR.
4. Request review—maintainers will review for code quality, test coverage, and alignment with project goals.

The complete contribution guidelines are documented in CONTRIBUTING.md (lines 7-34).

Summary

• Qwen Code uses an npm workspace monorepo with packages for core logic (packages/core), CLI (packages/cli), and SDK (packages/sdk-typescript).
• Development requires Node 20.19.0 managed via nvm, plus Git for version control.
• Build order follows test-utils → core → cli → webui → SDK → VS Code companion as orchestrated by scripts/build.js.
• Quality gates include npm run preflight (lint, format, test) and pre-commit hooks that prevent broken commits.
• Contributions require Conventional Commits, linked GitHub issues, and passing CI checks before merge.

Frequently Asked Questions

What Node version do I need to contribute to Qwen Code?

Development strictly requires Node 20.19.0 to ensure consistent builds across all contributor environments. You should install and activate this version using nvm (nvm install 20.19.0 && nvm use 20.19.0). While production deployments support any Node version ≥ 20, the build scripts and test suite are validated specifically against 20.19.0.

How do I run the Qwen Code CLI locally after building?

After running npm run build, you can launch the interactive terminal UI by running npm start from the repository root. This executes the compiled entry point at packages/cli/dist/index.js. For headless execution, use the qwen command directly with flags like qwen -p "Explain this file" to process prompts without entering the interactive interface.

What checks must pass before I can submit a pull request?

All pull requests must pass the preflight check, which runs automatically in GitHub Actions CI. Locally, you can verify this by running npm run preflight, which executes ESLint, Prettier formatting checks, and the full test suite. Additionally, the repository includes a pre-commit hook that runs these checks to prevent broken commits from entering your branch history.

Where is the core logic located in the Qwen Code repository?

The core agent logic resides in packages/core, which handles model providers, session management, and the AI agent orchestration. The command-line interface that wraps this logic is located in packages/cli, while the TypeScript SDK for building extensions lives in packages/sdk-typescript. The build orchestrator at scripts/build.js compiles these packages in dependency order, ensuring packages/core builds before the CLI and SDK that depend on it.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}