What is .cursorignore? (keeping files out of your AI's sight)

What it actually is

.cursorignore is a plain text file you create at the root of your project. Each line holds a pattern, written exactly like the patterns in .gitignore, and any file that matches drops out of Cursor’s AI features. The Agent won’t open it, Tab won’t autocomplete from it, Inline Edit won’t touch it, and it stops showing up when you type @ to reference files in chat.

Think of it as the do-not-enter list you hand a contractor working in your house: they have the run of the place while they work, except the rooms on the list.

The name trips people up because it looks like .gitignore and works like .gitignore, yet it guards a different thing. .gitignore keeps files out of your git history, so they never get committed or pushed to GitHub. .cursorignore keeps files away from the AI’s eyes inside the editor. A file listed only in .gitignore never leaves your machine, but Cursor’s Agent can still open it and read every line. There’s a third file in this family, and they divide up like this:

File	Keeps files out of	Can the AI still read them?
.gitignore	your git history and pushes to GitHub	Yes. Cursor skips them when indexing, but the Agent can open them
.cursorignore	the index, plus Agent, Tab, Inline Edit, and @ mentions	Blocked in the editor, with terminal and MCP exceptions
.cursorindexingignore	codebase search (the index) only	Yes, whenever they’re relevant

Why your AI just did this

Cursor builds a search index of your codebase so its features can find relevant code fast. Out of the box it already skips everything .gitignore excludes, plus a default list that covers lockfiles and .env*. That sounds reassuring until you notice what it applies to: the index. Indexing and access are separate. A file that never got indexed can still be opened and read the moment the Agent decides it matters, and agents love opening .env while they debug a connection string. .cursorignore is the file that closes that gap.

Your agent also brings the term up on its own. Ask it about a file that matches one of your patterns and it has to answer without ever reading the contents, because access is blocked for the Agent. And when your project drags around a huge folder (exported data, generated docs, thousands of test fixtures), the agent may suggest ignore files to keep the noise out of the index and out of your context window.

When you’ll run into it

The first sighting is often a scare. You scroll back through a chat transcript, find the Agent quoting values straight out of your .env, and a worried search lands you on the Cursor forum threads about controlling file visibility. That is the moment most people create the file.

You’ll also meet it in Cursor’s settings, where the indexing screen shows what made it into the index, and where a toggle named Hierarchical Cursor Ignore makes Cursor look for .cursorignore files in parent directories too. It shows up mid-conversation as well: an @ mention that won’t autocomplete a file you can plainly see in your file tree usually means a pattern is matching it. When that block surprises you, check the project root before you assume Cursor is broken.

What to check

• Add .env and every other secrets file to both .gitignore and .cursorignore. One keeps them out of your git history, the other keeps them away from the AI. Anything with keys in it counts, because exposed API keys are the most expensive mistake in vibe coding
• Put the file at your project root, one pattern per line, same syntax as .gitignore (*.pem, secrets/, config.json)
• Know the holes before you rely on it: Cursor’s docs state that terminal and MCP tools used by the Agent are not blocked by .cursorignore, and that complete protection isn’t guaranteed. An agent running cat .env in the terminal still sees your keys
• Move real secrets out of reach instead of hiding them: store production values as environment variables on your hosting platform, so there’s nothing in the folder to leak
• Use .cursorindexingignore for bulky but harmless folders you want out of search results while keeping them readable on request
• Don’t expect negation patterns to rescue files inside an excluded folder. Cursor skips excluded directories entirely, so !data/keep.md does nothing if data/ is ignored

Say it like a dev

Instead of: “make Cursor stop reading my secret file” Say: “Add .env* to .cursorignore, and confirm it’s in .gitignore too so it never gets committed.”

Instead of: “why can’t you open that file” Say: “Is that file blocked by .cursorignore? Show me the patterns and tell me which one matches.”

Instead of: “hide this huge folder, it slows everything down” Say: “Add data/ to .cursorindexingignore so it stays out of codebase search but you can still read it when I ask.”