Qwen Code began as a project built on Google’s Gemini CLI, and today it has more than 30,000 GitHub stars of its own. The README says the project was originally based on Gemini CLI v0.8.2, then stopped syncing with upstream from v0.1 and grew into an independent, multi-protocol coding agent.
Key takeaways
- Qwen Code is an open-source, Apache-2.0 coding agent for the terminal that began as a Gemini CLI fork.
- Install it with the standalone script, npm with Node.js 22 or newer, or Homebrew, then run /auth to connect a model.
- No sign-in option is described as free, so use a local Ollama, vLLM or LM Studio server for zero cost.
- Start new codebases in read-only Plan Mode, review with /diff and roll back with /restore.
This guide shows how to install Qwen Code, sign in (or point it at a free local model), and use it safely on a real project. Everything below comes from the project’s own README and docs on GitHub, checked on 15 November 2026. None of the commands were run for this article, so try them in a throwaway folder first.
What you need
- A terminal on macOS, Linux or Windows
- Node.js 22 or newer, if you choose the npm route
- A code project to point it at (a spare repo is ideal)
- A way to pay for or host a model: a Qwen subscription, an API key, or a local model server

What Qwen Code is
It is an open-source coding agent that runs in your terminal, reads your repo, edits files and runs commands. GitHub lists Apache-2.0 as the license, and the README says it works with OpenAI, Anthropic, Gemini and Qwen APIs, plus any third-party provider or local model such as Ollama or vLLM. As of 15 November 2026 the latest release tag is v0.27.4.
The project also reports its own benchmark: on SWE-bench Verified, seven Qwen Code versions averaged between 76.40% and 77.80% with the same Qwen 3.7 Max model. That is the maintainers’ evaluation, not an independent test.
By the numbers
30,000GitHub stars, more than
77.80%top self-reported SWE-bench avg
v0.27.4latest release tag
Step by step
1. Install it
The README gives three routes. The first is a one-line installer on Linux and macOS:
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash
Piping a script into your shell is a trust decision. The installer is hosted on an Alibaba Cloud storage address, so if you prefer, use npm or Homebrew instead:
npm install -g @qwen-code/qwen-code@latest
Or, on macOS and Linux with Homebrew:
brew install qwen-code
Windows users get a PowerShell installer in the README. After a standalone install, restart your terminal so the environment variables take effect.
2. Start it inside a project
cd ~/projects/my-app
qwen
You should see an interactive terminal session. The README also mentions a “1.0 Preview” branch, but the instructions here are for the main version.
3. Sign in or connect a model
Type /auth. The docs list five top-level choices:
- Qwen Account with Subscription: browser sign-in with a Plus or Pro subscription.
- QwenCloud: a Token Plan or a pay-as-you-go Standard API Key.
- Alibaba ModelStudio: Coding Plan, Token Plan or Standard API Key.
- Third-party Providers: a built-in list including DeepSeek, Kimi, OpenRouter and others, using an API key.
- Custom Provider: a local server, proxy or unsupported provider.
None of those options is described as free in the current docs. To keep costs at zero, use a local model. The docs show that Ollama, vLLM and LM Studio work through an OpenAI-compatible address. Our guide to running an AI model with Ollama covers the server side. Then save a config at ~/.qwen/settings.json, adapted from the docs’ own example:
{
"env": { "OLLAMA_API_KEY": "ollama" },
"modelProviders": {
"openai": [
{
"id": "your-model-name",
"name": "My local model",
"envKey": "OLLAMA_API_KEY",
"baseUrl": "http://localhost:11434/v1"
}
]
},
"security": { "auth": { "selectedType": "openai" } },
"model": { "name": "your-model-name" }
}
Replace your-model-name with the exact model name your server reports. The docs say model.name must match one of the id values. After saving, run qwen.
4. Ask your first question
The README suggests starting with a safe, read-only prompt:
Explain this repository and show me where to start.
Then run /init, which the docs describe as analyzing the current directory and creating an initial context file. Qwen Code loads your QWEN.md and AGENTS.md briefings automatically. If you already use skill files, our guide to agent skills in Claude Code explains the idea, and Qwen Code lists its own /skills panel in the docs.
5. Choose how much freedom it gets
Qwen Code has five permission modes: Plan, Ask Permissions, Auto-Edit, Auto and YOLO. Press Shift+Tab (Tab on Windows) to cycle through them. The docs call Auto, where a classifier approves safe actions and blocks risky ones, the default out of the box, but the same page also names Ask Permissions as the initial mode, so check the status bar. For a new codebase, start in Plan Mode:
/plan refactor the settings page
Plan Mode is read-only, so nothing is edited or executed. Type /plan exit to restore your previous mode. Save YOLO for trusted projects, as the docs advise.
6. Review and undo
Use /diff to open an interactive viewer of uncommitted changes. If a step went wrong, /restore lists checkpoints and reverts project files to the state before a tool call ran.
7. Use it in scripts
The README says headless mode runs from scripts and CI:
qwen -p "Summarize the repository layout."

Common errors and fixes
qwen: command not found. Restart your terminal after installing, as the README instructs. For npm, confirm Node.js is version 22 or newer.- Browser sign-in will not work. In CI or unattended containers, the auth docs say to use an API-key method instead, with environment variables.
qwen authdoes nothing useful. That command has been removed. Runqwen, then/auth. Run/doctorto check your current authentication.- Local model times out. Confirm the
baseUrlends in/v1and the server is running. For slow servers the docs describe astreamIdleTimeoutMssetting. - Unsure the daemon is safe. If you use
qwen serveorqwen daemon start, note that the README says it listens on loopback without bearer authentication by default, so any local process that can reach it can use the full API, including code execution. On shared hosts, setQWEN_SERVER_TOKENand use--require-auth.
Did you know?
By default the qwen serve daemon listens on loopback without bearer authentication, so any local process that can reach it can use the full API, including code execution. Set QWEN_SERVER_TOKEN and use –require-auth on shared hosts.
Is it worth trying?
If you like the Claude Code or Gemini CLI workflow and want something you can point at your own model, Qwen Code is a short install away. Start in Plan Mode, keep a Git commit handy, and treat the benchmark figures as the maintainers’ own until you have tried it.
Frequently asked questions
Is Qwen Code free to use?
The tool itself is open source under Apache-2.0, but none of the /auth sign-in options is described as free in the current docs. To keep costs at zero, connect it to a local model through Ollama, vLLM or LM Studio.
How do I install Qwen Code?
The README gives three routes: a one-line standalone installer on Linux and macOS, npm install -g @qwen-code/qwen-code@latest with Node.js 22 or newer, or brew install qwen-code. Windows users get a PowerShell installer. Restart your terminal afterward.
Can Qwen Code use a local model with Ollama?
Yes. Save a ~/.qwen/settings.json that points an OpenAI-compatible provider at http://localhost:11434/v1, and make sure model.name matches one of the provider id values. Then run qwen.
What is Plan Mode in Qwen Code?
Plan Mode is one of five permission modes and is read-only, so nothing is edited or executed. Start it with /plan followed by your task, and type /plan exit to return to your previous mode.
Quick quiz
Which project was Qwen Code originally based on?
- Claude Code
- Gemini CLI
- Ollama
The README says it was originally based on Gemini CLI v0.8.2.
Which mode is read-only?
- Plan
- YOLO
- Auto-Edit
The docs say Plan Mode edits and executes nothing.
Which command reverts project files to a checkpoint?
- /diff
- /init
- /restore
/restore lists checkpoints and reverts files to the state before a tool call ran.
Sources
Links last checked on 15 November 2026.





Write a response