Cursor Ignore File (.cursorignore): Syntax, Setup and Context Optimization

How Cursor Blocks Files Across AI Features

Placing a pattern in .cursorignore creates a barrier across Cursor's primary AI features. According to Cursor ignore file documentation, files matched by .cursorignore are blocked from three specific surfaces:

• Code accessible by Cursor Agent and Tab autocomplete.
• Code accessible through manual @ mention references in chat and composer.
• Background semantic search and vector codebase indexing.

When a file is ignored, Cursor's language models will not read its contents during inline code generation, will not index it into the semantic search database, and will block users from attaching it via @filename. However, an important boundary exists: the integrated terminal and Model Context Protocol tools used by Cursor Agent run outside native editor file filters. If an agent is instructed to run a shell command like cat .env or execute an MCP tool against an absolute path, the terminal process can still read the underlying disk contents. True secret isolation requires keeping sensitive credentials entirely outside the repository boundary.

The Difference Between .cursorignore and .gitignore

Developers often ask whether a separate .cursorignore file is necessary when a comprehensive .gitignore is already present. Cursor automatically respects .gitignore rules by default. If a directory like node_modules/ or dist/ is listed in .gitignore, Cursor excludes it from codebase indexing without additional configuration.

The primary purpose of .cursorignore is defining exclusions that apply exclusively to Cursor's AI features while keeping those files tracked in Git. Common examples include:

• Static fixtures and mock JSON payloads needed for unit test suites but too verbose for AI prompts.
• Third-party SDK vendor bundles checked into the repository for deterministic builds.
• Generated database migration histories containing thousands of repetitive schema snapshots.
• Proprietary intellectual property, internal customer datasets, or compliance documents that developers want committed to source control but shielded from third-party model inference.

By separating Git tracking from AI indexing, teams maintain full version control without polluting the vector store used by Cursor's code generation models.

Differences Between .cursorignore and .cursorindexingignore

Cursor also supports a specialized configuration file named .cursorindexingignore. While .cursorignore creates a universal block across all AI capabilities (disabling Agent inspection, Tab autocomplete, chat mentions, and vector embeddings), .cursorindexingignore restricts files exclusively from background codebase indexing.

This distinction is valuable when developers maintain large reference scripts, utility helpers, or schema definitions that should not consume embedding resources during background scans, but may still need to be referenced manually during Chat or Composer sessions via @filename. When you want complete isolation, use .cursorignore; when you want to reduce vector indexing overhead while preserving on-demand AI access, use .cursorindexingignore.

Sample Production .cursorignore Template

Below is a production-ready .cursorignore template suitable for modern full-stack web and backend applications:

# environment variables and secret stores
.env
.env.*
*.pem
*.key
**/secrets.json
**/credentials.json

# build artifacts and compiled outputs
dist/
build/
out/
.next/
.nuxt/
target/
*.tsbuildinfo

# package manager locks and dependency caches
node_modules/
.venv/
__pycache__/
package-lock.json
yarn.lock
pnpm-lock.yaml
bun.lockb

# large datasets, logs, and database dumps
*.log
*.sqlite
*.csv
*.parquet
tests/fixtures/large_payloads/
assets/raw_recordings/

# generated code and documentation builds
generated/graphql-client.ts
docs/_build/
coverage/
.nyc_output/

Negation Rules and the Nested Directory Trap

A frequent pitfall when configuring .cursorignore involves negation patterns. When you use the ! prefix, you cannot re-include a file if its parent directory was already matched and skipped by a wildcard directory pattern. This limitation mirrors Git's underlying directory traversal architecture.

Consider this broken configuration:

# broken configuration: attempts to ignore public but keep style.css
public/*
!public/assets/style.css

In this example, public/* matches the assets/ subfolder. For performance reasons, Cursor's file scanner stops traversing excluded directories immediately. Because the scanner never opens public/assets/, it never evaluates the negation rule !public/assets/style.css. The CSS file remains ignored.

To fix this issue, avoid broad wildcard directory matches when specific nested files must remain accessible. Instead, target nested folders explicitly:

# working configuration: exclude assets folder contents while preserving specific files
public/assets/*
!public/assets/style.css

By targeting public/assets/* rather than public/*, Cursor walks down into the assets folder, discovers style.css, and honors the negation rule.

Files Cursor Automatically Excludes by Default

Cursor ships with an extensive built-in default ignore list designed to protect system stability. Even if your .gitignore and .cursorignore files are empty, Cursor's background indexer skips common binary formats, package lockfiles, and virtual environment directories.

The default ignore list includes:

• Package lockfiles: package-lock.json, pnpm-lock.yaml, yarn.lock, composer.lock, Gemfile.lock, bun.lockb.
• Version control folders: .git/, .svn/, .hg/.
• Binary executables and libraries: *.bin, *.exe, *.dll, *.so, *.dylib, *.vsix.
• Documents and media: *.pdf, *.doc, *.docx, *.xls, *.xlsx, *.ppt, *.pptx, *.jpg, *.jpeg, *.png, *.gif, *.mp4, *.mov, *.zip, *.tar.gz, *.parquet.
• Virtual environments and caches: node_modules/, .venv/, .egg-info/, __pycache__/, .next/, .nuxt/, .pytest_cache/, .mypy_cache/, .DS_Store.

If you genuinely need Cursor to index a file that falls into the default list, such as a reference data.csv or a specific documentation guide.pdf, you can override the default exclusion by adding an explicit negation pattern in your project's .cursorignore file, such as !data/reference.csv.

When to Exclude Files Versus Moving Them to Remote Storage

Deciding whether an asset belongs in .cursorignore or in a remote workspace depends on its role in the development lifecycle:

• Exclude via .cursorignore: Transient build outputs, compiled binaries, minified packages, package manager lockfiles, coverage reports, and local environment files. These files change constantly, offer no semantic value to code generation, and should never be indexed.
• Move to a remote workspace: Technical architecture documents, API schemas, product requirements, database schema documentation, and reference PDFs. These assets contain essential specifications that AI coding agents must query, but storing them as raw text in the Git tree degrades local editor performance.

By storing external documentation in a dedicated cloud workspace such as Fast.io storage for agents, your local Git repository remains lightweight and responsive.

Connecting Cursor to Fast.io Workspaces via MCP

Fast.io provides intelligent workspaces designed for human and AI collaboration. Files can be uploaded directly or brought in through Cloud Sync. Cloud Sync connects Google Drive, Dropbox, Box and OneDrive folders to a workspace, one-way or two-way, on a schedule or on demand. Once you create a workspace and store your project documentation, you can enable Intelligence Mode. Intelligence Mode automatically indexes your uploaded files for hybrid search, combining full-text search, semantic vector search, and metadata filtering. Instead of forcing Cursor to embed hundreds of megabytes of documentation locally, Cursor connects to Fast.io over Streamable HTTP using a remote MCP server.

For coding agents like Cursor, Fast.io serves a dedicated MCP endpoint at https://mcp.fast.io/mcp/code. You can configure Cursor to connect to your Fast.io workspace by adding an entry to your project's .cursor/mcp.json file or your user-level ~/.cursor/mcp.json configuration:

{
  "mcpServers": {
    "fast-io": {
      "url": "https://mcp.fast.io/mcp/code"
    }
  }
}

When Cursor connects to https://mcp.fast.io/mcp/code, it prompts you to authenticate via OAuth. During sign-in, you select your organization, choose the workspace containing your project documentation, and grant permissions. Step-by-step setup instructions are detailed in the Fast.io MCP documentation, and agent tooling specifications are described in Fast.io skill guide and Fast.io LLM reference.

Once connected, Cursor Agent can execute search actions against your indexed workspace documents. When you ask Cursor, "What are our rate limit policies according to our API architecture guide?", Cursor queries the Fast.io workspace through MCP, retrieves the exact cited paragraphs, and uses them to complete your code. Your local repository stays unencumbered by heavy documentation, your .cursorignore stays concise, and your AI assistant gains access to company-wide technical knowledge.