Does Qwen Code Read AGENTS.md? Yes — Straight From the Source Code (2026)

Qwen Code reads AGENTS.md automatically as of March 2026 — you no longer need to touch settings.json to make it work. It loads AGENTS.md alongside QWEN.md, not instead of it, and the two files are not treated equally: only one of them gets written back to when you run /init or /remember. If you searched for this because an older blog post or GitHub issue told you to manually set contextFileName, that advice is now half-obsolete — this guide covers exactly what changed, sourced from the CLI’s own TypeScript, not secondhand summaries.

Quick answer

Two GitHub issues, eight months apart

Search “qwen code agents.md” today and you’ll still find Issue #504, opened in early 2026, asking the maintainers to support the AGENTS.md standard by default instead of requiring users to manually add "contextFileName": "AGENTS.md" to their settings file. The maintainers closed it — the workaround already existed, so there was no bug to fix. That closed issue is what most of the current search results and AI-tool summaries are still citing, and it’s why the internet’s current answer to “does Qwen Code read AGENTS.md” is “only if you configure it.”

That answer is outdated. A second, more specific issue — #2006, opened February 28, 2026 — asked for the same thing but explicitly noted that #504’s “just configure it manually” answer wasn’t good enough for teams also running Codex, Copilot, or Cursor against the same repo, all of which read AGENTS.md out of the box. That issue shipped as PR #2018, merged March 2, 2026, and a follow-up fix in PR #2082 patched an edge case where a /context reset could silently drop AGENTS.md from the loaded set. Both are in every release since.

What the source code actually says

Qwen Code’s context-filename logic lives in packages/core/src/utils/memory-constants.ts. Here’s the relevant part, unmodified:

export const DEFAULT_CONTEXT_FILENAME = 'QWEN.md';
export const AGENT_CONTEXT_FILENAME = 'AGENTS.md';

// This variable will hold the currently configured filename for context files.
// It defaults to include both QWEN.md and AGENTS.md but can be overridden by setMemoryFilename.
// QWEN.md is first to maintain backward compatibility (used by /init command tool).
let currentMemoryFilename: string | string[] = [
  DEFAULT_CONTEXT_FILENAME,
  AGENT_CONTEXT_FILENAME,
];

Two things worth noticing that no changelog line spells out:

1. The default is an array, not a single filename. Out of the box, Qwen Code is looking for both QWEN.md and AGENTS.md at every level of the directory hierarchy — not falling back to AGENTS.md only when QWEN.md is absent.
2. Order is deliberate. The comment is explicit that QWEN.md stays first “to maintain backward compatibility with /init command and save_memory tool.” That ordering has a real behavioral consequence, covered next.

The source files still carry Copyright 2025 Google LLC headers — Qwen Code started life as a fork of Google’s Gemini CLI, and the settings architecture (layered settings.json, hierarchical context-file discovery, an /init-generated project file) is the same lineage. If you’ve configured Gemini CLI before, the shape of this will be familiar even though the specific AGENTS.md handling described here is Qwen-specific.

How discovery actually works

Qwen Code builds its instructional context by walking the filesystem and checking for every filename in the current list (both QWEN.md and AGENTS.md by default) at each of these locations:

1. Global scope — ~/.qwen/QWEN.md and ~/.qwen/AGENTS.md, if either exists. Applies to every project.
2. Project root and ancestors — starting from your current working directory, Qwen Code walks upward through parent directories until it hits either a .git folder (project root) or your home directory, checking for both filenames at each level.
3. --include-directories paths — if context.loadFromIncludeDirectories is true, the same search runs against any extra directories you’ve added to the workspace.

Everything found gets concatenated into one system-prompt block, with separators marking where each file came from. The CLI’s status footer shows a running count of loaded context files, so if you have a monorepo with three AGENTS.md files and one root QWEN.md, you’ll see “4 context files loaded” — not a merged single count. You can inspect the exact assembled content (and the load order) from the /memory dialog at any time, which is the fastest way to confirm what’s actually in context before you debug a prompt that isn’t landing.

The part that trips people up: reads both, writes one

This is the detail that the “yes it’s supported now” headline hides. Two built-in mechanisms only ever touch QWEN.md:

• /init — analyzes your project and writes a starter context file. It always creates QWEN.md, even in a repo that already has a well-maintained AGENTS.md. Run /init in an existing Codex/Copilot project and you’ll end up with two files that need to stay in sync, not one.
• /remember and the background auto-memory system (memory.enableManagedAutoMemory) — when Qwen Code extracts a durable instruction from a session and saves it, it appends to the file under the ## Qwen Added Memories header. That file is whichever one getCurrentMemoryFilename() resolves to, and with the default array, that resolves to the first non-empty entry — QWEN.md.

Practically: if your team’s source of truth is AGENTS.md because Codex and Copilot are also reading it, Qwen Code’s own memory features will keep depositing new instructions into a second file you didn’t ask for. Either treat QWEN.md as Qwen-specific scratch space and periodically fold anything useful back into AGENTS.md by hand, or reorder the array (see below) so AGENTS.md is what gets written to.

QWEN.local.md: the one file that isn’t in the hierarchy

Separate from the two-file default is QWEN.local.md, anchored to a fixed location: <projectRoot>/.qwen/QWEN.local.md. Per the source comment, it’s designed to be gitignored and hold “personal instructions (local cluster IDs, account names, paths) without polluting the shared project QWEN.md or the global ~/.qwen/QWEN.md.” Unlike the two default filenames, it isn’t part of the upward directory search — it’s loaded from one fixed slot per project, after every other project-level context file, so it can override or supplement shared instructions without you having to remember to .gitignore a file that lives at the repo root. There’s no AGENTS.local.md equivalent; if you need a personal override layer today, it has to go through QWEN.local.md, not the AGENTS.md side of the pair.

Configuring it yourself (settings.json)

If the two-file default doesn’t fit your setup — say, you want AGENTS.md only, with nothing written to QWEN.md — set context.fileName explicitly. This is the current, documented key; older issues and blog posts reference a flat contextFileName key from before Qwen Code’s settings schema was reorganized into nested groups (context.*, tools.*, ui.*, and so on). The CLI auto-migrates old-format settings files on load and backs up the original, so either key may show up depending on when a given repo’s config was written — but context.fileName is what current versions read and write.

{
  "context": {
    "fileName": "AGENTS.md"
  }
}

Or keep both, but flip the write priority so new memories land in AGENTS.md first:

{
  "context": {
    "fileName": ["AGENTS.md", "QWEN.md"]
  }
}

Place this in .qwen/settings.json for a single project, or ~/.qwen/settings.json to apply it to every project on your machine. Project settings override user settings, which override system defaults — the usual four-file precedence chain Qwen Code inherited from its Gemini CLI ancestry.

Three setups, depending on what else you run

Qwen Code only. Leave the default alone. You get QWEN.md and AGENTS.md both read, QWEN.md as the effective single source of truth for anything Qwen writes back, and no config to maintain.

Qwen Code + Codex + GitHub Copilot, one shared AGENTS.md. Set context.fileName to "AGENTS.md" only, in a project-level .qwen/settings.json committed to the repo, so every teammate’s Qwen Code session picks it up automatically. This is the setup that makes Qwen Code behave like the other two for read purposes. Just remember /init inside Qwen Code will still try to create QWEN.md if run — override the filename before the first /init, not after.

Qwen Code + Claude Code. These don’t overlap: Claude Code doesn’t read AGENTS.md at all, only CLAUDE.md. If you’re running both, you likely already have a CLAUDE.md with @AGENTS.md imported at the top (Anthropic’s own documented pattern). Qwen Code ignores CLAUDE.md entirely — set context.fileName to "AGENTS.md" on the Qwen side and the same source file feeds both tools without a symlink.

FAQ

If I already have an AGENTS.md written for Codex, will Qwen Code use it without changes? Yes, no changes needed, as long as you’re on a version that includes PR #2018 (anything from March 2026 onward — check with qwen --version, or just run /memory and see if AGENTS.md shows in the loaded list). Nothing about the file’s content needs to be Qwen-specific; it’s read as plain context the same way the other tools read it.

Does having both QWEN.md and AGENTS.md in the same directory cause a conflict? No — both get loaded and concatenated, in the order configured (QWEN.md first by default). If they contain contradictory instructions, you’re relying on the model to reconcile them, the same problem you’d have with any two context files loaded together. Keep one as the authoritative source and treat the other as supplementary, rather than maintaining two independent rule sets.

Does this match what Gemini CLI does? Not necessarily — Qwen Code forked Gemini CLI’s architecture early on and has since diverged (the workflow/goals/subagent features covered above don’t exist in vanilla Gemini CLI). Verify Gemini CLI’s own current defaults separately rather than assuming parity; see our Gemini CLI integration guide for that tool specifically.

Is any of this in the official Qwen Code settings docs? Partially. The settings reference documents context.fileName as a generic string-or-array setting and describes QWEN.md as the example context file, but doesn’t call out AGENTS.md as a default anywhere in the prose — you have to already know to look for it, or read the source. That gap is exactly why both GitHub issues kept getting filed.

Qwen Code isn’t a niche side project at this point — the repository sits at 27,600+ GitHub stars and the @qwen-code/qwen-code package cleared 85,000 npm downloads in the last week alone, with releases shipping several times a week. A default this actively used shifting under you without a changelog headline is worth checking directly against the source rather than trusting the first search result — which, as of this writing, is still often the year-old “you have to configure it manually” answer.

For a broader map of which coding agents read which config file, see our AGENTS.md vs CLAUDE.md tool support map, and if a context file you know is present still isn’t showing up in a session, our AGENTS.md not loading debugging guide covers the tool-by-tool verification steps. Browse more real-world instruction files, including AGENTS.md examples from production repos, in our gallery.