.cursorignore is a file in your project root that tells Cursor which files its AI may not touch. Anything it matches is blocked from Agent, from Tab autocomplete and from @ mention references, using the same pattern syntax as .gitignore. It is useful for secrets and noise, but it is not a hard security boundary: the terminal and MCP tools Agent uses can still reach ignored files.
This guide covers how to write one, what Cursor already ignores, its limits, and where .cursorindexingignore fits. It is based on Cursor's ignore file reference and ignore files help page, read on 26 October 2026.
What does .cursorignore block?
Per the reference, Cursor blocks files listed in .cursorignore from:
- Code accessible by Agent and Tab
- Code accessible via
@mention references
Cursor's Agent troubleshooting page puts it slightly more broadly: files listed there "are blocked from Agent, codebase search, and @ mentions." The Agent security docs add that reading files and searching code don't need your approval, so .cursorignore is the tool for keeping Agent away from specific files.
Cursor gives two reasons to use it:
- Security: keep API keys, credentials and secrets out of AI context.
- Performance: in large codebases or monorepos, exclude irrelevant parts "for more accurate file discovery."
How do you write a .cursorignore file?
Create .cursorignore in your project root. The syntax is the same as .gitignore:
# build output and dependencies
dist/
build/
node_modules/
# minified bundles
*.min.js
# secrets
.env*
config/credentials.json
# logs anywhere in the tree
**/logs
The pattern rules from the reference:
| Pattern | Meaning |
|---|---|
* |
Any characters except / |
** |
Any characters including / |
? |
A single character |
! |
Negates a pattern (un-ignores a path) |
# at line start |
Comment |
| Trailing spaces | Ignored unless escaped with \ |
To check whether a pattern matches what you expect, the reference suggests testing with git check-ignore -v [file].
Can .cursorignore be nested?
By default Cursor reads the file in your root directory. To make it search parent directories for .cursorignore files too, turn on Cursor Settings > Indexing > Ignore Files > Hierarchical Cursor Ignore.
What does Cursor ignore by default?
You often need less in .cursorignore than you think. Cursor already skips:
- Everything in your
.gitignore. The help page says "Cursor automatically respects your.gitignorepatterns." - A long built-in default list, which includes lock files (
package-lock.json,pnpm-lock.yaml,yarn.lock,*.lock),.env*,.git/,node_modules/,.venv/,__pycache__/,.next/and.cache/, plus images, audio, video, archives, fonts, office documents,*.csv,*.pdfand*.svg.
So .cursorignore is mainly for extra exclusions: generated code you commit, large fixtures, vendored libraries, or private config that isn't in .gitignore.
If you need the AI to see something on the default list, override it with ! in .cursorignore. For example, !data/schema.csv would re-include one CSV file.
What should a typical .cursorignore include?
Since .gitignore and the default list already cover dependencies, lock files and most binaries, a good .cursorignore is usually short. Look for files that are committed to the repo but add nothing useful to the AI's context:
- Generated code you commit, such as API clients, GraphQL types or protobuf output. The AI should read the source schema, not thousands of generated lines.
- Large fixtures and snapshots, like recorded HTTP responses or test snapshots that would crowd out real code.
- Vendored libraries copied into the repo, which are third-party code Cursor's help page calls "rarely useful as context."
- Private config that is committed for deployment but holds values you'd rather not send to a model.
Start small, then add a pattern whenever you notice Agent opening files it shouldn't.
Can you set a global ignore list?
Yes. The reference describes global ignore patterns in user settings that apply to every project, so you don't need a file in each repo. The list is empty by default. Cursor suggests patterns like these:
- Environment files:
**/.env,**/.env.* - Credentials:
**/credentials.json,**/secrets.json - Keys:
**/*.key,**/*.pem,**/id_rsa
What are the limits of .cursorignore?
Know these before you trust it with anything sensitive.
Terminal and MCP tools can bypass it. The reference states: "The terminal and MCP server tools used by Agent cannot block access to code governed by .cursorignore." If Agent runs cat .env in the terminal, or an MCP server reads files itself, the ignore file does not stop it. Review terminal commands before you approve them.
Protection is not guaranteed. In Cursor's words: "While Cursor blocks ignored files, complete protection isn't guaranteed due to LLM unpredictability." The safest secret is one that isn't in the repo at all.
Negation has a catch. You cannot re-include a file if its parent directory is excluded with *, because excluded directories are not traversed. This matches how Git handles nested negation:
public/*
!public/index.html # works: top-level file
!public/assets/style.css # does not work: nested
The fix from the docs is to exclude the nested folder explicitly, then re-include the file:
public/assets/*
!public/assets/style.css
It can hide files you wanted. If Agent "can't find" a file, check .cursorignore and .gitignore first. The troubleshooting page also suggests reindexing (search for "Reindex" in the command palette) or attaching the file with @. The Cursor troubleshooting guide covers more fixes.
What about .cursorindexingignore?
Many older tutorials describe a second file, .cursorindexingignore, as an index-only list: files in it stayed out of codebase search results but could still be used by AI features if you referenced them.
As of 26 October 2026, Cursor's current ignore file reference documents only .cursorignore, and the old indexing help URL now redirects to the ignore files page. Cursor's search docs describe Instant Grep, which "builds and queries its index on your machine," and say Cursor "does not store embeddings of your codebase for search." Because .cursorindexingignore is no longer in the docs, don't rely on it. Use .cursorignore for anything you want kept from the AI, and .gitignore for anything that shouldn't be in the repo.
When should you use .cursorignore instead of rules or hooks?
Each tool solves a different problem:
| Need | Use |
|---|---|
| Keep files out of Agent, Tab and @ context | .cursorignore |
| Tell Agent how to behave or which patterns to follow | Cursor rules |
| Run your own checks before or after agent actions | Cursor hooks |
| Keep secrets out of the repo entirely | .gitignore plus a secrets manager |
A common setup is to ignore build output and secrets in .cursorignore, then add a rule asking Agent never to print environment variables in the terminal. The rule is a request, not a guarantee, which is why the ignore file and good secret hygiene still matter.
Keep shared config with your prompts
Ignore files, rules and prompts are all plain text that you end up copying between projects. Prompts and Agent Skills are easiest to reuse when they live in one place. Kipt keeps them as Markdown in a private GitHub repo you own, so you can search and copy them into any project. For prompts written for Cursor's Agent, see the Cursor prompts collection.