Fixing Roo Code Custom Modes That Don't Appear in the Mode Selector or Ignore Their Own Tool Restrictions

The Problem

A custom mode is defined — typically to restrict the agent to a specific task shape, like reviewing code without editing it, or working only within a particular directory — and one of two things goes wrong. Either the mode never appears in Roo Code's mode selector at all, as if the definition was never read; or it does appear and can be selected, but the restrictions it was supposed to enforce (blocking file edits, limiting which tool groups are available) simply don't apply, and the agent does exactly what the mode was configured to prevent.

Why It Happens

Custom modes can be defined in more than one location, and Roo Code only reads from specific, exact places

Roo Code supports both a global custom-modes configuration and a project-level one, typically a .roomodes file at the workspace root. A mode added to the wrong one of these — a global config edited when the project expected a local .roomodes file, or vice versa — simply never gets picked up for that workspace, with nothing in the UI specifically telling the user it looked in the wrong place; the mode just silently doesn't exist from the extension's point of view.

A syntax error in the mode definition file fails the entire parse, not just that one field

Mode definitions are structured data — JSON or YAML, depending on the file — and a single malformed entry (a missing comma, incorrect indentation, an unescaped quote inside a string) typically isn't tolerated as a partial failure limited to that one mode. It commonly breaks parsing for the whole file, meaning every custom mode defined alongside the broken one can vanish from the selector at once, which makes the actual cause look less obvious if attention goes straight to the newest mode rather than the file as a whole.

A mode's tool-group restrictions only take effect if the restriction is expressed in the format the mode schema actually expects

Restricting a mode to certain tool groups (read-only tools, for instance, excluding anything that edits files) depends on the groups field being structured exactly as the mode schema expects — the right group names, the right nesting for any file-pattern restrictions within a group. A typo in a group name, or a restriction expressed in a shape the schema doesn't recognize, is commonly treated as if that restriction simply wasn't specified at all, silently falling back to unrestricted behavior rather than raising a visible error about the malformed entry.

The Fix

1. Confirm which file the mode is actually defined in, and that it's the one Roo Code is reading for this workspace

# Project-level custom modes — check this exists and is the one being edited:
cat .roomodes

# Global custom modes live in the extension's own settings location —
# use Roo Code's own "Prompts" / mode-settings UI to confirm which scope
# a given mode is actually registered under.

Verifying the actual file path a mode lives in, and cross-checking it against which scope (project vs. global) the current workspace is expected to read from, rules out the single most common cause — a mode defined in the wrong place rather than a bug in mode loading itself.

2. Validate the mode definition file's syntax independently, rather than assuming Roo Code would report a parse error

# For a YAML-based .roomodes file:
python3 -c "import yaml, sys; yaml.safe_load(open('.roomodes'))"

# For a JSON-based config:
python3 -m json.tool < custom_modes.json > /dev/null

Running the file through a dedicated parser outside the extension surfaces the exact syntax error — a line number, a specific malformed token — that a silent failure inside Roo Code itself might not display anywhere visible, turning "modes just disappeared" into a concrete, fixable parse error.

3. Check the mode's groups restriction against the exact format Roo Code's schema expects, not an assumed or remembered shape

customModes:
  - slug: review-only
    name: Review Only
    groups:
      - read
      # "edit" intentionally omitted to block file edits
    source: project

Comparing the mode's actual groups entry against Roo Code's current documented schema — rather than a remembered or copied structure that may be out of date with the current version — catches the case where a restriction is silently ignored because it's expressed in a shape the schema doesn't recognize, rather than because enforcement itself is broken.

4. After any fix to the definition file, reload the window rather than assuming the change is picked up live

Command Palette -> "Developer: Reload Window"

Custom mode definitions are commonly read once rather than watched continuously for changes, so a fix to the underlying file may not be reflected in the mode selector until the editor window is explicitly reloaded, which rules out the case of a correct fix that simply hasn't been picked up yet.

Why This Works

Each step narrows down a specific link in the chain between writing a mode definition and it actually taking effect. Confirming the file location addresses the most common root cause directly. Validating syntax independently surfaces a parse error precisely, rather than leaving it as an unexplained disappearance. Checking the restriction format against the actual schema catches the case where enforcement silently no-ops because of a shape mismatch rather than a genuine bug. And reloading the window rules out stale state as the explanation for a fix that looks correct but hasn't visibly taken hold yet.

Conclusion

A custom mode that won't appear, or that appears but doesn't enforce its own restrictions, is almost never a flaw in how Roo Code applies mode restrictions — it's the definition living in the wrong file, a quiet syntax error breaking the whole file's parse, or a restriction expressed in a shape the schema doesn't actually recognize. Confirm the mode is defined in the scope the workspace actually reads from, validate the file's syntax with an independent parser rather than assuming silence means it's fine, check the groups restriction against the current schema rather than a remembered shape, and reload the window after any fix rather than assuming it applies immediately.