AGENTS.md for Roo Code: Complete Setup and Configuration Guide (2026)

Roo Code reads AGENTS.md automatically — no toggle to flip, no extension setting to hunt for on a fresh install. What actually trips people up is something the one-line “it just works” answer skips entirely: where AGENTS.md sits relative to Roo Code’s own .roo/rules/ system, how it interacts with Custom Modes (Roo Code’s signature feature), and what the AGENT.md singular fallback does if you’ve typed the filename wrong without realizing it. This guide covers the setup end to end, plus the parts of Roo Code’s rule-loading model that the one-paragraph docs summary leaves out.

Does Roo Code Support AGENTS.md?

Yes, natively, since version 3.24.0 (July 2025). Drop an AGENTS.md file in your workspace root and Roo Code loads it automatically on every session — no config change required. The setting that controls this is roo-cline.useAgentRules in VS Code settings, and it defaults to true. You’d only touch it if you specifically want to turn AGENTS.md loading off:

{
  "roo-cline.useAgentRules": false
}

A few behaviors worth knowing before you write the file:

• Empty or whitespace-only AGENTS.md is silently ignored. Roo Code won’t error, it just won’t add anything to the prompt.
• Symbolic links are resolved before reading (added in v3.25.4), so a symlinked AGENTS.md pointing at a shared file in a monorepo works as expected.
• The file must be at the workspace root. Roo Code doesn’t walk up parent directories looking for it the way some tools do.

Where AGENTS.md Fits in Roo Code’s Rule-Loading Order

This is the part most coverage skips, and it matters because Roo Code already has its own native rule system (.roo/rules/, .roorules, mode-specific rule directories) that predates AGENTS.md support. When Roo Code assembles the system prompt, it concatenates instructions from every source in this exact sequence:

1. Language preference and Prompts-tab instructions (Global + mode-specific)
2. Mode-specific rule directories: .roo/rules-{modeSlug}/ (or .roorules-{modeSlug} as fallback)
3. .rooignore-related instructions
4. AGENTS.md or AGENT.md (from the workspace root, if present and enabled)
5. Generic rule directories: ~/.roo/rules/ and .roo/rules/
6. .roorules (fallback, only used if no generic rules directory has files)

The practical implication: AGENTS.md is not a replacement for .roo/rules/ — it’s inserted between your mode-specific rules and your generic workspace rules. All of it ends up concatenated into a single prompt block, so nothing here is a strict override like CSS specificity; it’s an ordering of sections, not a conflict-resolution mechanism. But the ordering still matters for one practical reason: if you’re migrating a project to AGENTS.md and leaving old .roo/rules/ files in place “just in case,” both get loaded, every session, and you’re paying double context budget for duplicated instructions.

When Roo Code loads AGENTS.md, it wraps the content with a labeled header so you can see exactly what got included if you inspect the system prompt:

# Agent Rules Standard (AGENTS.md):
[contents of your AGENTS.md file]

(Or (AGENT.md): if that’s the file Roo Code found instead — more on that below.)

Setting Up AGENTS.md: Step by Step

1. Create the file at your workspace root.

touch AGENTS.md

2. Write it for what actually changes Roo Code’s behavior. Skip prose about “clean code” — Roo Code, like every AGENTS.md-reading agent, treats vague guidance as noise it can’t act on. Lead with commands, since Roo Code can’t verify its own output without knowing how to run your test suite:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Test: `pnpm test`
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`
- Build: `pnpm build`

## Repository Layout
src/routes/       # Route handlers only — no business logic
src/services/     # Business logic
src/repositories/ # All database queries, nowhere else

## Conventions
- No `any` types — TypeScript strict mode is on
- Errors: return `Result<T, E>`, never throw across module boundaries

## Verification
Before calling a task done, run and confirm passing:
1. `pnpm test`
2. `pnpm typecheck`
3. `pnpm lint`

## Do Not
- Modify `src/generated/` — regenerated by `pnpm codegen`
- Commit directly to `main`

3. Commit it. AGENTS.md is meant to be version-controlled, same as .roo/rules/. If it only lives on your machine, teammates running Roo Code against the same repo get a worse-informed agent than you do.

4. Confirm it loaded. Start a fresh chat and ask Roo directly — see the verification section below.

AGENTS.md vs Roo Code’s Native .roo/rules/ System

Roo Code had its own rule format before AGENTS.md support existed, and it’s more granular than what AGENTS.md alone can express. Here’s how they compare:

The honest tradeoff: AGENTS.md is portable across tools but flat — no mode-specific branching. .roo/rules-{modeSlug}/ is Roo Code-specific but lets you scope instructions to Architect mode vs. Debug mode vs. Code mode. Most teams end up using both, which is the next section.

Combining AGENTS.md with Custom Modes

Custom Modes are Roo Code’s actual differentiator — specialized personas (Architect, Debug, Code, or ones you define) each with their own tool permissions and instruction set. AGENTS.md doesn’t know modes exist; it loads the same content regardless of which mode is active. That’s a feature, not a gap, if you use it correctly: put the things that are true no matter what Roo Code is doing (build commands, repo layout, security rules) in AGENTS.md, and put the things that only apply to a specific kind of session in .roo/rules-{modeSlug}/.

my-project/
├── AGENTS.md                    # Universal: commands, layout, conventions
├── .roo/
│   ├── rules-architect/
│   │   └── 01-design-rules.md   # Only loaded in Architect mode
│   └── rules-debug/
│       └── 01-investigation.md  # Only loaded in Debug mode
└── src/

AGENTS.md (excerpt, universal):

## Commands
- Test: `pnpm test`
- Type check: `pnpm typecheck`

## Repository Layout
src/routes/    # Route handlers
src/services/  # Business logic

.roo/rules-debug/01-investigation.md (Debug mode only):

# Debug Investigation Protocol

Before proposing a fix:
1. Reproduce with a minimal case
2. Identify the exact line producing the unexpected value
3. Check git blame for when the behavior changed

Never suggest "catch and return null" — fix the root cause.

Switch to Debug mode and Roo Code’s prompt contains both the universal AGENTS.md content and the debug-specific protocol, stacked. Switch to Ask mode, and only the AGENTS.md content shows up, since there’s no .roo/rules-ask/ directory in this example. This split is worth doing deliberately rather than dumping everything into one giant AGENTS.md — Factory’s and Anthropic’s own guidance on AGENTS.md-style files both note that smaller, targeted files outperform one file trying to cover every mode’s concerns at once.

The AGENT.md Fallback (Singular)

Since v3.25.13 (August 2025), Roo Code also recognizes AGENT.md — singular — as a fallback if AGENTS.md isn’t present. This exists because of a real, recurring mistake: enough people were typing the singular form by habit (or copying conventions from a tool that uses the singular) that it warranted a fix. The rule is simple:

• If AGENTS.md exists, Roo Code uses it and ignores AGENT.md even if both are present.
• If only AGENT.md exists, Roo Code falls back to it.

Practically, this means a typo doesn’t silently fail — but it’s still worth naming the file correctly. If you’re maintaining a project that other AGENTS.md-aware tools also read (Claude Code, Codex, Cursor), stick to the plural AGENTS.md; it’s the form specified by the open standard, and it’s the one Roo Code checks first.

Loading AGENTS.md from Subfolders (Monorepos)

If your workspace contains multiple git repositories or packages, each with its own AGENTS.md, Roo Code doesn’t discover them by default. As of v3.38.3 (January 2026), there’s an opt-in Context setting — enableSubfolderRules — that turns on recursive discovery of both .roo/rules/ and AGENTS.md files from subdirectories:

{
  "enableSubfolderRules": true
}

With it enabled, Roo Code searches for .roo directories and AGENTS.md files across the whole workspace tree (using ripgrep under the hood) and loads them in this order: global rules, then root-level rules, then subfolder rules alphabetically. Each subfolder rule’s file path is shown in the prompt so you can tell which package’s instructions are in play. This is off by default — if you have a monorepo and Roo Code seems to be ignoring a package-level AGENTS.md, this setting is very likely why.

Verifying Roo Code Actually Loaded Your AGENTS.md

Writing the file and confirming it’s in context are two separate steps. The fastest check: open a fresh chat, before giving Roo Code any real task, and ask it directly.

> What repository rules do you currently have loaded, and where did they come from?

A working setup names your actual commands, your actual conventions, your actual file paths — not a generic “I’ll follow best practices” answer. If you get the generic answer, walk through these in order:

1. Is the file actually at the workspace root? Not a subdirectory, unless enableSubfolderRules is on.
2. Is roo-cline.useAgentRules set to false somewhere in your settings (user, workspace, or an org-level policy)? That silently disables the whole feature.
3. Is the file empty or whitespace-only? Roo Code ignores it without complaint.
4. Does AGENT.md exist alongside AGENTS.md? It shouldn’t cause a problem — AGENTS.md wins — but if you meant to edit one and accidentally have both with different content, that’s worth catching.
5. Are you opening the correct workspace root in VS Code? If your repo is nested inside another folder you opened, Roo Code is looking for AGENTS.md at the folder VS Code considers root, not necessarily your git root.

Migrating from CLAUDE.md or .cursorrules

One thing worth being explicit about, since other AGENTS.md-supporting tools handle this differently: Roo Code does not read CLAUDE.md as a fallback. Its recognized filenames are AGENTS.md and AGENT.md only — nothing else. If your team already maintains a CLAUDE.md for Claude Code and wants Roo Code to pick up the same instructions, you have two workable options:

• Copy the content into AGENTS.md. The most reliable option if the CLAUDE.md content doesn’t lean on Claude Code-specific syntax like @file import references, which Roo Code has no reason to resolve.
• Symlink it: ln -s CLAUDE.md AGENTS.md. Works because Roo Code resolves symlinks before reading, but means both tools now depend on one file staying generic enough for both — drop this the moment either tool’s instructions diverge.

Migrating from .cursorrules or a flat .clinerules file is more direct, since neither has a competing modes concept: paste the content into AGENTS.md, drop anything that’s genuinely Cursor- or Cline-specific (tool names, feature references), and keep the rest.

Is Roo Code Still Actively Maintained?

Worth addressing directly, since it affects whether investing time in an AGENTS.md setup is worthwhile: no, not by the original team. Roo Code, Inc. co-founder Matt Rubens announced in April 2026 that the company was pivoting away from IDE-based coding tools entirely, and the VS Code extension was formally shut down on May 15, 2026. The GitHub repository (RooCodeInc/Roo-Code) is now archived and read-only, and v3.54.0 — published the day after the shutdown — is the final release. The company’s new product, Roomote, is not a rebrand of the extension; it’s a separate cloud-based, Slack/GitHub/Linear-integrated autonomous agent, and roocode.com now redirects to it.

The extension itself hasn’t disappeared, though. It’s still installable from the VS Code Marketplace at v3.54.0 with its existing install base intact, and the AGENTS.md/AGENT.md support this guide covers ships in that final build — it’ll keep working for as long as you’re on that version. What you’re not getting going forward is new development from the original team: no further model-provider additions, no bug fixes, no security patches. If you want an actively developed fork, look at ZooCode (community continuation of the codebase) or Cline (the project Roo Code originally forked from) — both read AGENTS.md the same way. For a repo already standardized on AGENTS.md, none of the rules or file format documented here change if you migrate to either.

What Not to Put in AGENTS.md

This isn’t Roo Code-specific — it’s true for every AGENTS.md-reading tool — but it’s worth restating because it’s the most common way teams make the file worse than useless:

• Secrets, API keys, or credentials of any kind
• A full copy of your README (duplicated content doesn’t help, it just consumes prompt budget)
• Exact dependency versions or file counts that go stale within a week
• Vague instructions that don’t change behavior (“write good code,” “be careful”)
• Instructions telling Roo Code to skip its own verification steps

Frequently Asked Questions

Do I need to enable a setting for Roo Code to read AGENTS.md? No. It’s on by default via roo-cline.useAgentRules (default true). You’d only touch this setting to turn AGENTS.md loading off.

What’s the difference between AGENTS.md and .roo/rules/? AGENTS.md is a single file at the workspace root, portable across AI coding tools. .roo/rules/ is a Roo Code-specific directory of multiple files, loaded alphabetically, with mode-specific variants (.roo/rules-{modeSlug}/) that AGENTS.md has no equivalent for. Both load simultaneously — they’re not either/or.

Does Roo Code read CLAUDE.md? No. Roo Code’s recognized filenames are AGENTS.md and AGENT.md only. If you have a CLAUDE.md, either copy its content into AGENTS.md or symlink it, provided the content doesn’t depend on Claude Code-specific syntax.

What happens if I have both AGENTS.md and AGENT.md? AGENTS.md (plural) always wins. AGENT.md (singular) is only used as a fallback when AGENTS.md doesn’t exist.

Does AGENTS.md apply differently per Custom Mode? No — AGENTS.md content loads identically regardless of active mode. For mode-specific instructions, use .roo/rules-{modeSlug}/ alongside AGENTS.md rather than instead of it.

Can Roo Code find AGENTS.md files in subdirectories of a monorepo? Only if you enable enableSubfolderRules in Context settings. It’s off by default; when off, Roo Code only reads the AGENTS.md at your workspace root.

How do I confirm Roo Code actually loaded my AGENTS.md? Start a fresh chat and ask Roo Code what repository rules it currently has loaded and where they came from. A specific answer naming your actual commands confirms it; a generic “best practices” answer means it isn’t finding the file.

Related Reading on The Prompt Shelf

• Roo Code Rules Guide: Custom Modes, .roo/rules/, and Mode-Specific Instructions (2026) — the full custom modes system in depth
• Cline vs Roo Code Rules (2026)
• AGENTS.md for Factory Droid: Complete Setup and Configuration Guide (2026)
• AGENTS.md for OpenAI Codex: Complete Setup and Configuration Guide (2026)
• AGENTS.md Not Loading? How to Debug It in 2026

Browse real-world AGENTS.md files across different stacks in our rules gallery.