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

> Contribute to Qwen Code by cloning the repo, installing Node 20.19.0, and running build and preflight commands. Learn how to set up the dev environment and submit pull requests.

- Repository: [Qwen/qwen-code](https://github.com/qwenlm/qwen-code)
- Tags: how-to-guide
- Published: 2026-02-19

---

**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](https://github.com/nvm-sh/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.

```bash

# 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`](https://github.com/QwenLM/qwen-code/blob/main/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`](https://github.com/QwenLM/qwen-code/blob/main/scripts/build.js) handles the sequence automatically.

```bash

# Build all packages in dependency order

npm run build

```

The build process follows this specific sequence as defined in [`scripts/build.js`](https://github.com/QwenLM/qwen-code/blob/main/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:

```bash
BUILD_SANDBOX=1 npm run build

```

This triggers [`scripts/build_sandbox.js`](https://github.com/QwenLM/qwen-code/blob/main/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.

```bash

# 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`](https://github.com/QwenLM/qwen-code/blob/main/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:

```bash
npm run test

```

### Run Preflight Checks

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

```bash
npm run preflight

```

This command runs ESLint, Prettier formatting checks, and all test suites as mandated by [`CONTRIBUTING.md`](https://github.com/QwenLM/qwen-code/blob/main/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:

```bash
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:

```bash
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`](https://github.com/QwenLM/qwen-code/blob/main/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`](https://github.com/QwenLM/qwen-code/blob/main/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`](https://github.com/QwenLM/qwen-code/blob/main/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`](https://github.com/QwenLM/qwen-code/blob/main/scripts/build.js) compiles these packages in dependency order, ensuring `packages/core` builds before the CLI and SDK that depend on it.