Guides for Qwen Code

Qwen Code began as a fork of Gemini CLI, and the split shows in what it reads and where it keeps it: two default instruction-file names, QWEN.md and then AGENTS.md; a default approval mode called Auto; and configuration under ~/.qwen and .qwen rather than ~/.gemini and .gemini. An instruction file here is a Markdown file Qwen loads at the start of every session and puts in the model's prompt. Auto is the mode that sends tool calls to a classifier instead of asking about each one. A guide written for Gemini CLI can send a Qwen user to the wrong file, the wrong mode, or the wrong folder; these pages start from what Qwen actually does.

Run qwen --version before you use a page here. This set was checked against Qwen Code's documentation and source at v0.26.2 on 27 October 2026.

Start with the problem#

QWEN.md and AGENTS.md: what Qwen Code loads, in what order, and how to check — Both names are defaults, and the load order is built name by name; the page gives the checks that prove what reached the model.

Why Qwen Code keeps asking for permission after you chose "Always allow" — The mode, the session decision and the saved rule are separate layers, and a higher ask rule can still beat the rule you saved.

Where did my Qwen Code session go? — The picker follows the folder you launched from, not the repository, so the transcript you want may be under another project folder.

Using Qwen Code with a local or OpenAI-compatible model — A local Qwen3.x name can inherit the commercial 1M window, so the footer percentage and the compaction trigger can both be wrong.

Qwen Code says MCP is connected: why the tools are still missing — An MCP (Model Context Protocol, how Qwen loads external tool servers) server can report connected while the model has no tools; the page walks the gates between configuration and the model's function list.

Why your Qwen Code skill or subagent never activates — A skill's description is the trigger, and a subagent file can be skipped silently; the page shows where to check.

Hooks: the event names are Claude Code's#

Qwen Code's core hook event names are the ones Claude Code uses, not Gemini CLI's event set: PreToolUse, PostToolUse, SessionStart, Stop and the rest of the table below. A hook is an entry under the top-level hooks key in settings.json that runs a command, HTTP request, prompt, or in-process function at one of those points (hooks documentation). If you have a Claude Code hook whose event and tool name already match, the shape will look familiar. The command and the matcher still need checking against Qwen's own tool ids.

Qwen also fires events beyond that core set, including PostToolUseFailure, PermissionRequest, PermissionDenied, InstructionsLoaded, and TodoCreated. Each is documented with its input and output fields.

Run /hooks to open a read-only browser of what the current session runs. It moves from events to matchers to the individual hooks, and it re-reads the settings files when you open it, so a new definition can take effect without a restart. disableAllHooks turns everything off and does need a restart. Project hooks load only in a trusted folder. Matchers are regular expressions, and Bash, Read and Write are accepted as aliases for the runtime tool ids, which is why a matcher copied from a Claude Code config can work unchanged (matcher rules).

There is no Gemini-style policy file here. Hard rules are permissions.deny entries and hooks that return a deny decision. The permissions page covers the rule layers; this hub's hooks table is only the map of when a hook runs.

Rewind: `/rewind` puts back a turn and its files#

/rewind (alias /rollback) opens a selector of earlier turns in the interactive terminal. For the turn you pick, Qwen offers conversation only, and, when that turn has captured file changes, code and conversation together or code only. The file half comes from snapshots under ~/.qwen/file-history/, kept for general.cleanupPeriodDays: 30 days by default, with 0 leaving about an hour (settings reference). Pressing Esc twice with an empty prompt, outside IDE mode, opens the same selector.

Two limits matter more than the menu:

• It only sees edits made through Qwen's file tools. A file changed by a shell command or by hand is outside the snapshot, and the selector says so.
• A compressed turn cannot be rewound. Qwen answers "Cannot rewind to a turn that was compressed. Try a more recent turn." That message is still in the v0.26.2 source (session-rewind.ts), and an open report describes the same behaviour (#4046, open since 11 May 2026).

/restore restores a tool-call checkpoint: it puts the project files and the conversation back to the state when that tool call was suggested. /rewind is the turn picker: it lets you choose a turn and then take the conversation, the files, or both. File checkpointing is on by default in interactive mode and unavailable when the tool sandbox is active (commands).

Memory, context and handoff#

Context compaction explains what a long session loses when older turns are replaced by a summary, including Qwen's meter, its 0.85 ceiling, and /compress-fast. That page carries the general mechanism; this hub does not repeat it.

Persistent memory for Claude Code and Codex is the cross-tool comparison. For Qwen, the durable boundary is between QWEN.md, which you write and which loads every session, and auto-memory, which Qwen writes under ~/.qwen/projects/<project>/memory/ and which is best-effort. The memory pages cover the checks and the corrections.

Hand off work between Claude Code and Codex is the written baton for work that moves between tools or sessions. It also carries the Claude Code and Gemini CLI to Qwen Code checklist: what to rename, what to reinstall, and what not to copy.

The concepts page on instruction files, skills and memory compares the mechanisms across agents.

Other agents#

The Claude Code guides cover nested CLAUDE.md files, auto memory, subagents, sessions, permissions, and hooks. The Codex guides cover the AGENTS.md chain and its size limit, config.toml, sessions, approvals, hooks, and undo. The OpenCode guides cover the V1 and V2 lines, instructions, sessions, permissions, undo, and plugins. The GitHub Copilot CLI guides cover instructions, skills, custom agents, sessions, permissions, and hooks. The Gemini CLI guides are the closest relatives on paper, but Qwen has diverged; read the Qwen page before carrying a Gemini answer across. The Cursor guides cover Cursor's rules, skills, chat history, permissions, hooks and MCP.