@file references in .cursor/rules/*.mdc are not expanded by the CLI agent

Support Bug Reports
, ,
1

Where does the bug appear (feature/product)?

Cursor CLI

Describe the Bug

The rules docs say “Use @filename.ts to include files in your rule’s context” (Rules | Cursor Docs, FAQ), and the CLI docs say “The CLI agent supports the same rules system as the editor” (Using Agent in CLI | Cursor Docs, Rules).

In the CLI, an always-applied rule is loaded, but a file it references with @ is not included. The agent sees the literal text @notes.md and not the file’s contents.

Steps to Reproduce

In an empty git repository, create two files.

notes.md:

The secret word is "heron".

.cursor/rules/notes.mdc:

---
description: Project notes
alwaysApply: true
---

The other word is "walrus".

@notes.md

Then run:

cursor-agent -p --mode ask --trust "Do not use any tools. From your loaded rules only: what is the secret word, and what is the other word? Answer UNKNOWN for any you were not given."

Actual: the other word is walrus; the secret word is UNKNOWN. The agent reports that the rule “points at @notes.md” but that its contents were not loaded. --output-format stream-json shows no tool calls.

Expected Behavior

The agent answers heron and walrus, because the contents of notes.md are included in the rule’s context.

Operating System

MacOS

Version Information

CLI Version 2026.10.01-e373342
OS: darwin (arm64), macOS 27.0

Additional Information

The same happens with @file in a root AGENTS.md. Model: Auto.

Does this stop you from using Cursor

No - Cursor works, but with this issue

5

Hey @Paul_Draper, thanks for the clear repro.

You’re right that the docs overstate this. Right now, an @notes.md line inside a rule (or AGENTS.md) is passed to the agent as a pointer, not inlined, and that’s the same in the editor and the CLI. The agent sees the reference and reads the file with its Read tool when it decides it needs it. Your prompt tells it not to use tools, so it can’t open the file and answers UNKNOWN.

I’ve passed this to the team so the docs and the behavior can be lined up.

In the meantime:

  1. If the content must always be in context, paste it directly into the rule body (or AGENTS.md).
  2. If a pointer is fine, make it explicit, e.g. “Before answering, read notes.md”, and let the agent use tools. Running your same command without “Do not use any tools” should show it reading notes.md and answering heron.
7

Okay, thanks. I confirmed that this is correct.