You ask Cursor to “replace every useAuth with useSession across the project,” it touches 3 files, and grep -rn useAuth src/ still shows 17 hits. That is not laziness. Cursor literally cannot see the other 17 files. They were excluded from the codebase index, the workspace was opened at the wrong level, or your prompt never pointed at the right directory. Cursor (and Windsurf, Cline, and other IDE-embedded agents) can only edit files that are both in the codebase index and in the chat’s context window. Miss either and the file is invisible.
Fastest fix: open the chat, type @Folder for each directory the change touches and @File for the key files, then end the prompt with “list every file path you changed.” Hard @ pins bypass embedding retrieval entirely, so they are the single most reliable lever. If @Folder itself comes up empty, your index is the problem. Jump to Step 1.
Which bucket are you in?
| Symptom | Most likely cause | Go to |
|---|---|---|
@Folder x returns nothing or far fewer files than exist | Directory excluded from the index by .gitignore / .cursorignore | Step 1 |
| Workspace name (bottom-left) is a subfolder, not the repo root | Opened at the wrong level | Step 2 |
| Index looks complete but the agent still skips files | Prompt relied on retrieval, not explicit pins | Step 3 |
| Agent guesses field/type names from generated code | A semantically-required dir is ignored | Step 4 |
| One giant file (schema, i18n, migration) is treated as nonexistent | File exceeds the per-file index size limit | Step 5 |
Common causes
Ordered by hit rate, highest first.
1. Indexing excluded critical directories
Cursor’s codebase index is shaped by four layers: .gitignore, .cursorignore, .cursorindexingignore, and Cursor’s own built-in default ignore list (node_modules, lockfiles, build artifacts, binaries, and media are skipped automatically). The classic miss is .gitignore excluding src/packages/ or apps/web/ (a habit from older monorepo setups), which silently removes them from the index too, because Cursor “automatically ignores files in .gitignore and the default ignore list.”
How to spot it: In Cursor, Cmd+Shift+P → “Cursor Settings” → Indexing (older builds: Features → Codebase Indexing). Compare the indexed file count against git ls-files | wc -l. A gap larger than 30% means lots of files are being skipped.
2. Workspace opened at the wrong level
You opened Cursor in ~/projects/myapp/frontend/, but the backend and shared types live in ~/projects/myapp/backend/ and ~/projects/myapp/shared/. Cursor only indexes the current workspace root, so cross-package refactors silently miss the other halves.
How to spot it: Look at the workspace name in the lower-left. If it is a subdirectory rather than the monorepo root, you are hitting this.
3. The prompt never pinned the files
Even with a complete index, on long chats Cursor selects context by relevance plus token budget. Abstract prompts like “refactor the auth flow” rely on embedding retrieval, which skips files with non-obvious names or thin docstrings.
How to spot it: Expand the context pill / “Context used” panel under Cursor’s reply. It lists which files were actually read. Diff that against the files you expected to change.
4. An ignore rule hides files the agent still needs
Things like src/generated/ or prisma/client/ are build outputs but semantically critical: the agent needs them to know field and type names. Once they are in .gitignore (or .cursorignore) they are also out of the index, and the agent ends up guessing types.
How to spot it: grep -rn "from.*generated" src/. If the code imports heavily from a generated dir but an ignore rule excludes it, Cursor cannot see it.
5. Huge files are auto-skipped
Cursor skips files above its per-file index size limit (1 MB / 1048576 bytes by default, as of June 2026) to keep retrieval fast. If your schema, migration file, or i18n dictionary is a single giant file over that limit, the agent will behave as if it does not exist.
How to spot it: find src -type f -size +1M. Paste any hits into the chat and ask Cursor “do you see this file in your index?”
Shortest path to fix
Ordered by ROI. The first three usually solve it.
Step 1: Audit the codebase index scope
Open Cursor → Cmd+Shift+P → “Cursor Settings” → Indexing (older builds: Features → Codebase Indexing). Check:
- Indexed file count: compare to
git ls-files | wc -l - Status: should be a finished/synced state, not “Indexing” or “Stale.” Semantic search only becomes available at roughly 80% completion, so a stuck bar means partial context.
- Ignore rules: the panel reflects the effective
.gitignore+.cursorignore+.cursorindexingignore
The index auto-syncs about every 5 minutes and processes only changed files, so after a big directory move it can lag. If the indexed count is too low, temporarily comment out suspect ignore lines and trigger a rebuild: Cmd+Shift+P → Reindex Codebase, or click the re-index control in Settings → Indexing. You can also force a clean rebuild from the shell:
# Quit Cursor, then wipe the workspace index cache
rm -rf ~/Library/Application\ Support/Cursor/User/workspaceStorage/*/cursorIndex
# Relaunch Cursor — it will rebuild from zeroStep 2: Reopen the workspace at the monorepo root
If you opened a subdirectory, use File → Open Folder and pick the root. Or from the shell:
cd ~/projects/myapp # monorepo root
cursor . # relaunch Cursor at the rootAfter reopening, type @Folder frontend and @Folder backend in chat to verify both halves are reachable. If a folder shows no files in the picker, it is not indexed (back to Step 1).
Step 3: Pin files and folders explicitly in the prompt
Do not write “modify the auth logic.” Write:
@File src/lib/auth.ts @File src/hooks/useAuth.ts @Folder src/components/auth
Replace useAuth with useSession. Only modify the files I @-ed plus
their direct callers. After you finish, list every file path you changed.@File / @Folder / @Symbol are hard pins, much more reliable than embedding retrieval. Keep @Folder targets small: a folder with roughly 10 or fewer files fits cleanly, while pinning a huge directory can blow past the context budget and Cursor will sample it instead. For project-wide questions you can fall back to @Codebase, but for a precise refactor, explicit pins win. Claude Code users do the equivalent by hard-coding “always read these files first” in CLAUDE.md.
Step 4: Maintain a lean ignore set, and keep generated code referenceable
.cursorignore syntax matches .gitignore but only affects Cursor. A reasonable .cursorignore:
# Build output
dist/
build/
.next/
.astro/
out/
# Dependencies
node_modules/
vendor/
# Caches and logs
.cache/
.turbo/
*.log
coverage/
# Large generated data (case-by-case)
**/*.snap
public/locales/*.jsonBe careful about the difference between the two ignore files, because they behave differently:
.cursorignoreblocks files from all AI features (semantic search, Tab, Agent, and Inline Edit) and indexing. Use it for true noise..cursorindexingignoreexcludes files from the index only. They will not show up in codebase search, but they stay reachable with@File. This is the right home for large generated dirs you occasionally need to pin but do not want bloating the index.
Do not put src/generated/ or similar semantically-required directories in .cursorignore (the agent then cannot see them at all). If they are too big to index comfortably, list them in .cursorindexingignore instead and pin them with @File when needed.
Step 5: Raise the size limit or split the file
If a single file exceeds the per-file index limit (1 MB by default), the agent will skip it. You have two options.
Raise the limit in settings.json (Cmd+Shift+P → “Preferences: Open User Settings (JSON)”):
{
"cursor.maxFileSize": 2097152
}Or split i18n bundles, schemas, and route tables by module so each piece indexes cleanly:
# Example: split a large src/i18n/en.json by namespace
node scripts/split-i18n.mjs src/i18n/en.json src/i18n/en/Update imports, then Reindex Codebase.
How to confirm it’s fixed
- In Settings → Indexing, the indexed file count is within ~5% of
git ls-files | wc -land the status is synced. - In chat,
@Folderfor each affected directory lists the files you expect (no empty pickers). - Re-run the refactor with explicit
@pins and the “list every file you changed” instruction. The printed list should match what you expected. - Verify on the command line that nothing was missed:
grep -rn useAuth src/returns zero hits (substitute your own symbol). For larger refactors,git diff --statshould show every intended file.
Prevention
- Keep a minimal
.cursorignoreat the repo root: only build output and dependencies, neversrc/generated/, schemas, or migrations. Push large-but-needed generated dirs into.cursorindexingignoreinstead. - Before a large change, write “files I expect to be touched: a.ts, b.ts, c.ts” and have the agent confirm it can
@-reach all of them. - For monorepos, always open Cursor at the repo root and scope work with
@Folder packages/fooinstead of opening a subpackage. - Split any single file approaching the 1 MB index limit; for files that genuinely cannot be split (like auto-generated schemas), call them out in CLAUDE.md /
.cursorrulesand pin them with@File. - After a major dependency upgrade or directory reshuffle, manually run
Reindex Codebaseinstead of waiting out the ~5-minute auto-sync.
For the exact, current behavior of the two ignore files and the default ignore list, see Cursor’s docs: Ignore files and Semantic & agentic search.
FAQ
Why did Cursor only edit some of the files I asked it to change?
It only saw some of them. A file must be in the codebase index and pulled into the chat’s context window to be edited. The fix is to pin the rest with @File / @Folder and to confirm they are indexed in Settings → Indexing.
What is the difference between .cursorignore and .cursorindexingignore?
.cursorignore blocks a file from every AI feature (semantic search, Tab, Agent, Inline Edit) and from indexing. .cursorindexingignore only keeps it out of the index; you can still reference it manually with @File. Use the indexing-only file for large generated code you occasionally need.
How do I force Cursor to re-index?
Cmd+Shift+P (or Ctrl+Shift+P) → Reindex Codebase, or use the re-index control in Cursor Settings → Indexing. For a hard reset, quit Cursor, delete the workspace index cache, and relaunch.
Why is a large file being ignored?
Cursor skips files over its per-file index size limit (1 MB by default as of June 2026). Raise cursor.maxFileSize in settings.json, or split the file by module and re-index.
Does @Folder have a size limit?
There is no hard cap, but large folders overflow the context budget, so Cursor samples them instead of reading everything. Folders with roughly 10 or fewer files work best; for bigger ones, pin the specific @Files that matter.