# Cursor Codebase Size Limit: Indexing Caps and Large Repository Guide

The Cursor codebase size limit refers to the maximum repository size, file count, and individual file threshold that Cursor's background indexing engine embeds for semantic codebase search (@codebase). While Cursor processes small projects rapidly, large codebases with more than 10,000 files frequently suffer from indexing lag, synchronization stalls, and memory exhaustion. Configuring ignore rules and connecting external document workspaces via MCP keeps repository indexing fast and reliable.

Source: https://fast.io/resources/cursor-codebase-size-limit/
Author: [Tom Langridge](https://fast.io/authors/tom-langridge/)
Last reviewed: 2026-10-26

## What Defines the Cursor Codebase Size Limit: Background Caps and File Skips

The Cursor codebase size limit refers to the maximum repository size, file count, and individual file threshold that Cursor's background indexing engine embeds for semantic codebase search (@codebase). According to Cursor's engineering research on codebase indexing, semantic search remains unavailable until at least 80% of repository indexing finishes, and naive embedding runs across repositories with tens of thousands of files can take hours. Understanding these architectural caps helps development teams configure their workspaces so the AI pair programmer stays responsive rather than stalling on oversized assets.

Developers frequently confuse the context window of the active language model with the indexing capacity of the Cursor editor. When you ask a question using `@codebase`, Cursor does not paste your entire project into a prompt. Instead, a background process chunks your source files, generates mathematical vector embeddings, and stores them in a vector index. When you issue a prompt, Cursor queries this index to retrieve the most relevant code snippets and injects only those fragments into the prompt context.

Cursor applies rigid defaults to protect local hardware and network bandwidth. The background indexer automatically skips individual files larger than `1 MB`, ignoring non-text binary formats, minified scripts, and heavy log files. In addition, internal tool execution buffers throttle at `2 MB` for individual file reading operations. Repositories containing more than `10,000` files routinely experience background indexing stalls, elevated CPU consumption, and synchronization delays during branch switching. In massive monorepos approaching `100,000` files, unoptimized indexing can exhaust client resources completely.

### Vector Embeddings Versus Model Context Windows

Developers often assume that expanding context windows in models like Claude 3.7 Sonnet, Claude 3.5 Sonnet, and GPT-4o eliminates repository size limitations. This assumption overlooks the fundamental difference between prompt context and persistent vector search.

A model context window defines the total volume of tokens an LLM can evaluate in a single conversational turn. Frontier models offer context windows ranging from 128,000 to 200,000 tokens. However, stuffing an entire enterprise repository into an active prompt is financially prohibitive, introduces latency of several seconds per message, and degrades model attention. In contrast, platforms handling document attachments enforce different constraints; for instance, [Anthropic file upload documentation](https://support.claude.com/en/articles/8241126-upload-files-to-claude) specifies that Claude chats accept a fixed batch of attachments while Claude Projects accept larger individual files with no fixed file count cap, bounded only by the model context window.

| Platform or Tool | Background Indexing File Cap | Single File Size Threshold | Indexing Architecture | Source and Verification Date |
|---|---|---|---|---|
| Cursor (@codebase) | ~10,000 files optimal (degrades near 100,000) | 1 MB skip threshold (2 MB buffer cap) | Merkle tree synchronization with remote vector embeddings | Cursor Engineering (checked 2026-10-26) |
| Claude Chat | 20 files per conversation | 500 MB per file | Ephemeral prompt injection (no persistent index) | Anthropic Support (checked 2026-09-14) |
| Claude Projects | Unlimited file count (bounded by project context) | 30 MB per file | Project knowledge store bounded by context window | Anthropic Support (checked 2026-09-14) |
| GitHub Copilot | Repository-bounded symbol graph | 10 MB per file cap | Local workspace semantic index and Tree-sitter graph | GitHub Documentation (checked 2026-10-26) |
| Aider CLI | Bounded by upstream model window | No hardcoded file size cap | In-memory Tree-sitter repo map with PageRank symbol ranking | Aider Documentation (checked 2026-10-21) |

The comparison demonstrates that Cursor's `@codebase` operates on an indexing model rather than an attachment model. The index exists outside the prompt, serving as an on-demand retrieval mechanism. When indexing fails or stalls on massive repositories, `@codebase` loses visibility into unindexed files, forcing developers to manually attach code using `@file` or `@folder` tags.

### Merkle Tree Synchronization and the 80% Search Threshold

To minimize network transfer and local computation, Cursor tracks repository state through a cryptographic Merkle tree. Every source file receives a SHA-256 hash, and every folder hash is derived from the hashes of its child nodes.

When you modify code, only the edited file and its parent directories up to the workspace root change their cryptographic hashes. Cursor compares these local hashes against the server's index state to pinpoint exact file diffs. Matching branches are skipped entirely, while divergent files are queued for chunking and embedding. In a project containing `50,000` files, transmitting raw filenames and SHA-256 hashes consumes approximately `3.2 MB` of data per sync. Walking the Merkle tree avoids transferring this metadata repeatedly.

The operational bottleneck arises when opening a new repository or executing major git rebases across thousands of files. Reusing teammate index structures reduces Cursor's 99th percentile time-to-first-query from 4.03 hours down to 21 seconds. To achieve this, Cursor calculates a similarity hash (simhash) from the Merkle tree and queries team index caches. However, if the repository is unique or diverges widely from existing team indexes, Cursor must compute chunks from scratch. Because semantic search requires 80% completion before returning results, developers on large repositories face prolonged blind spots unless file ingestion is actively pruned.

## Why Large Repositories Degrade Cursor Indexing

When a codebase expands beyond a few thousand source files, the background indexing process shifts from an imperceptible background task to a resource-intensive workload. Enterprise repositories, polyglot monorepos, and projects with extensive historical assets frequently encounter indexing degradation.

The primary symptom of an overwhelmed indexer is Cursor remaining indefinitely in an "Indexing..." or "Syncing..." state in the bottom status bar. When this occurs, semantic search queries fail silently, fallback keyword matching returns partial results, and CPU usage on the developer's workstation spikes. Understanding why large repositories choke the indexer requires examining file discovery limits, Tree-sitter abstract syntax tree (AST) chunking, and file system event queues.

### File Count Thresholds and Merkle Tree Overhead

The number of files in a repository affects local memory consumption and file watcher responsiveness. While small web applications contain fewer than `2,000` source files, enterprise codebases routinely exceed `25,000` to `100,000` files once dependencies, build outputs, and documentation are included.

As file counts rise past `10,000` files, several structural issues emerge:

* **File System Watcher Exhaustion:** The editor relies on operating system notification interfaces (FSEvents on macOS, inotify on Linux) to detect file modifications. When a build tool generates thousands of intermediate files, event queues saturate, causing Cursor to miss changes or trigger redundant re-scans.
* **Tree Traversal Overhead:** Calculating SHA-256 hashes across tens of thousands of nested folders consumes CPU cycles. On laptops with thermal throttling, walking deep directory hierarchies creates perceptible interface stutter.
* **Vector Store Fragmentation:** Storing vectors for `100,000` files produces substantial vector database overhead. Managing these embeddings remotely requires continuous reconciliation, and network latency on corporate VPNs exacerbates synchronization stalls.

When a repository exceeds `10,000` active files, configuring explicit ignore boundaries ceases to be optional. Without pruning, Cursor spends more time reconciling file changes than assisting with code generation.

### High-Entropy Files and Syntax Chunking Failures

File size alone does not determine indexing cost; the internal structure of the file matters equally. Cursor breaks source files into semantic chunks based on language syntax trees, identifying functions, class declarations, and logical blocks.

High-entropy files disrupt this parsing mechanism:

1. **Massive Dependency Lockfiles:** Files like `package-lock.json`, `pnpm-lock.yaml`, and `Cargo.lock` often span several megabytes of dense, repetitive text. While technically structured, parsing millions of lines of dependency hashes provides zero semantic value for coding tasks while consuming extensive AST chunking budgets.
2. **Minified JavaScript and CSS:** Production bundles (`bundle.min.js`, `vendor.css`) pack hundreds of kilobytes of code onto a single line. Standard line-based and syntax-based chunkers struggle with extreme line lengths, causing parser timeouts or out-of-memory errors in the language server.
3. **Database Dumps and Datasets:** Static fixtures, SQLite test databases, and CSV or JSON mock data files introduce vast quantities of literal strings. Because Cursor skips files over `1 MB` for indexing, large fixtures are excluded, but fixtures hovering between `200 KB` and `900 KB` slip past the filter, crowding the vector space with irrelevant test tokens.
4. **Compiled WebAssembly and Source Maps:** Source maps (`.map`) and compiled binaries contain high-density symbol mappings that provide no conceptual utility to the LLM during feature development.

## How to Configure Ignore Files to Protect Index Health

The most effective way to eliminate indexing bottlenecks in Cursor is to establish granular ignore boundaries. Cursor provides two specialized ignore files in addition to standard git tracking: `.cursorignore` and `.cursorindexingignore`.

Configuring these rules properly allows engineering teams to filter out unnecessary generated code, heavy lockfiles, build artifacts, and test assets before the indexing daemon touches them. Understanding the functional distinction between these files prevents unintentional context loss. While both files use standard glob pattern syntax, they operate at completely different layers of the editor's AI architecture. Misconfiguring them can leave the AI blind to critical source files or, conversely, permit thousands of useless files to pollute the vector index.

### Syntax Rules and Exclusion Precedence

Cursor evaluates ignore rules in a strict hierarchy to determine how files are indexed and exposed to AI prompts:

* **`.gitignore` Rules:** Respected by default for both git tracking and codebase indexing. Any file pattern matched by `.gitignore` is skipped during background indexing. However, files ignored by git can still be manually passed to Chat or Composer if explicitly selected via `@file`.
* **`.cursorignore` Rules:** Functions as a complete exclusion boundary for Cursor's AI features. Files and directories matched in `.cursorignore` are blocked from background vector indexing, inline completions (Tab), the interactive Chat panel, Composer agent workflows, and `@` symbol lookups. If a file contains sensitive credentials, private keys, or proprietary data that must never reach an AI model, place it in `.cursorignore`.
* **`.cursorindexingignore` Rules:** Excludes files specifically from the background vector embedding index while leaving them accessible for direct interactive use. A file listed here will not be embedded for `@codebase` semantic queries, but a developer can still reference it manually using `@file` or open it in the editor for inline edits.

For large monorepos, `.cursorindexingignore` provides the ideal balance. It excludes massive generated artifacts and documentation archives from the vector index, keeping the repository well under the `10,000`-file degradation threshold, while retaining the ability to target specific files during manual debugging.

### Production Ignore Template for Monorepos

To configure ignore rules for a complex repository, create a `.cursorignore` or `.cursorindexingignore` file at the root of your project. The following production configuration filters out high-entropy files, generated assets, and large data corpora:

```text
# dependencies and package manager locks
node_modules/
vendor/
package-lock.json
pnpm-lock.yaml
yarn.lock
Cargo.lock
poetry.lock

# build outputs and compilation caches
dist/
build/
out/
.next/
.nuxt/
target/
*.tsbuildinfo

# test coverage, snapshots, and logs
coverage/
__snapshots__/
*.log
*.lcov
*.profraw

# large data fixtures and local databases
*.sqlite
*.sqlite3
*.db
*.csv
*.tsv
*.parquet
*.jsonl
test/fixtures/large/

# binary assets, multimedia, and documents
*.pdf
*.zip
*.tar.gz
*.wasm
*.png
*.jpg
*.jpeg
*.svg
*.mp4

# sensitive configuration and environments
.env
.env.*
*.pem
*.key
*.cert
```

Applying this template removes thousands of non-essential files from the indexer's queue, allowing Cursor to complete vector generation on your actual business logic within seconds.

### Clearing Corrupted Indexes and Verifying Index Status

If your repository was previously stuck in an indexing loop or indexing stopped progressing past a partial percentage, updating your ignore file will not always trigger an immediate cleanup. Cached index state can persist locally and remotely.

Follow this procedure to force a clean re-indexing cycle:

1. Open Cursor Settings using `Cmd + ,` on macOS or `Ctrl + ,` on Windows and Linux, or press `Cmd + Shift + J` (`Ctrl + Shift + J`) to access the Cursor panel.
2. Select **Features** in the sidebar, then open **Codebase Indexing**.
3. Inspect the current status display. The panel reports the total number of indexed files and the percentage completed.
4. Locate the index management controls and select **Delete Index** (or click the resync icon beside the status indicator).
5. Confirm deletion to wipe both the local Merkle tree cache and the remote vector store association.
6. Toggle **Codebase Indexing** off and back on, or click **Index Codebase** to restart ingestion.

With a properly configured ignore file in place, the status bar shows file discovery counts matching only active source directories, quickly reaching the completion threshold required for semantic search.

## Offloading Documentation and Non-Code Corpora to Remote Workspaces

Engineering teams frequently encounter a fundamental contradiction when managing repository size. On one hand, developers want Cursor to reference vast non-code corpora, including architectural decision records, extensive API specifications, compliance manuals, database schema catalogs, and product requirement documents. On the other hand, placing hundreds of megabytes of documentation, PDFs, and schema dumps inside the git repository triggers the exact indexing degradation and file skip limits that cripple editor responsiveness.

Traditional workarounds fail to resolve this tension. Storing documentation in local directories outside git makes team synchronization manual and fragile. Dumping documents into raw cloud storage buckets like Amazon S3 or Google Cloud Storage leaves the files unstructured and unindexed, requiring custom retrieval pipelines before an AI agent can read them. Commodity file sync drives lack native agent interfaces, structured schema extraction, and semantic search capabilities.

The sustainable architectural pattern is to decouple operational documentation from the code repository entirely. By placing non-code reference corpora into an intelligent cloud workspace such as [storage for AI agents](/storage-for-agents/) and exposing that workspace to Cursor via the Model Context Protocol (MCP), developers give their AI pair programmer immediate semantic access to documentation without adding a single byte to the local git working tree.

### Decoupling Documentation from Repository Vector Stores

Code repositories are designed to store executable instructions, not enterprise knowledge bases. When technical documentation, customer ticket dumps, and API schemas live inside git, they introduce several hidden penalties:

* **Vector Dilution:** In a unified repository index, search queries for specific business logic functions often return prose paragraphs from documentation rather than the implementation file, degrading prompt precision.
* **Clone and Watcher Bloat:** Every developer on the team must clone, track, and watch large documentation folders, increasing local memory usage across language servers and IDE extensions.
* **Format Blindness:** Cursor's background indexer skips PDF manuals, complex spreadsheets, and binary presentations entirely. Storing these formats in git yields zero indexability while inflating repository footprint.

Decoupling reference material into an external workspace resolves these problems. Source code remains lean, fast to index, and strictly focused on implementation. The documentation corpus resides in a dedicated environment optimized for multi-format ingestion, semantic retrieval, and structured field extraction.

### Connecting Cursor to Fast.io Over Streamable HTTP

Fast.io provides an intelligent cloud workspace platform for agentic teams, giving Cursor direct access to extensive external corpora through a consolidated remote MCP toolset. Instead of forcing Cursor's local background engine to index multi-gigabyte document archives, you store the files in an organization-owned Fast.io workspace where Intelligence Mode indexes them on arrival.

Cloud Sync connects Google Drive, Dropbox, Box, and OneDrive folders to a workspace, one-way or two-way, on a schedule or on demand. For complex unstructured documents like vendor agreements or API contracts, Metadata Views extract structured fields (Text, Integer, Decimal, Boolean, URL, JSON, Date & Time) into filterable schemas without manual OCR templates.

To connect Cursor to your Fast.io workspace, review the official [Fast.io MCP setup documentation](https://mcp.fast.io/docs) and configure the remote MCP server over Streamable HTTP:

1. Open or create your Cursor MCP configuration file at `~/.cursor/mcp.json` (for global editor access) or `.cursor/mcp.json` (within your project root).
2. Add the Fast.io coding agent endpoint to the `mcpServers` configuration block:

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

3. Save the file. Cursor detects the remote server and initiates OAuth sign-in through your web browser.
4. On the permissions screen, select your organization and target documentation workspace, then grant access.

Once connected, Cursor's Composer and Chat agents interact with the remote corpus using MCP actions. When you ask a question like "What is our company policy on JWT token expiration for internal microservices?", Cursor queries the Fast.io workspace via the `search` tool, retrieves the relevant passages with document citations, and incorporates the verified answer into your code suggestions. The local repository remains compact and fast, completely free of indexing bottlenecks.

Reviewing [Fast.io pricing plans](/pricing/) outlines options for growing teams. Monthly plans start with a 14-day free trial that requires a credit card. Subscriptions include Starter at `$9.99`/mo, Business at `$49.99`/mo, and Enterprise at `$199.99`/mo. Maximum upload limits are `25 GB` on Starter, `50 GB` on Business, and `100 GB` on Enterprise, accommodating extensive document and media archives.

## Practical Workflow Patterns for Multi-Gigabyte Repositories

Even after establishing strict ignore boundaries and offloading documentation to remote workspaces, enterprise developers must frequently work within massive codebases containing hundreds of thousands of lines of source code. Operating in these environments efficiently requires intentional workflow patterns that conserve editor memory and prevent vector search degradation.

By adopting modular repository views, focusing indexing scope on active microservices, and combining local lexical search with remote documentation lookup, development teams can maintain high velocity across repositories of any scale. Structuring workspace sessions around specific development goals prevents unnecessary resource contention, reduces background CPU load, and keeps code generation accurate across large distributed teams.

### Sub-Tree Scoping for Microservice Monorepos

In large microservice repositories or enterprise monorepos (such as NX, Turborepo, or Bazel setups), opening the repository root in Cursor forces the indexer to evaluate every independent service, shared library, and configuration script simultaneously.

Instead of opening the repository root, adopt sub-tree scoping:

* **Open Focused Service Roots:** Launch Cursor directly inside the specific sub-application you are actively modifying (for example, `cursor apps/billing-service`). The background indexer builds a dedicated vector map containing only the relevant service files, keeping the index well under `2,000` files.
* **Configure Multi-Root Workspaces:** In projects where cross-package references are necessary, define a multi-root workspace file (`.code-workspace`) that includes only the active service and its immediate shared libraries (for example, `apps/billing-service` and `packages/ui-components`), explicitly excluding sibling services.
* **Scoped `.cursorignore` Files:** Place nested `.cursorignore` files inside individual package directories to handle package-specific build outputs without cluttering the global root ignore configuration.

### Hybrid Search Strategies in Daily Development

Relying exclusively on `@codebase` for all code search tasks leads to suboptimal results in large repositories. Effective development teams combine multiple retrieval mechanisms based on the precision required:

1. **Instant Grep for Exact Symbols:** When searching for an exact function name, variable declaration, or error string, use Cursor's Instant Grep (`Cmd + Shift + F` or `Ctrl + Shift + F`). Instant Grep performs ripgrep-based text matching across the local file tree instantly without querying vector embeddings.
2. **Targeted Symbol Mentions (`@file` and `@folder`):** When you know which module contains the logic you want to refactor, mention the file or folder directly in Composer rather than triggering `@codebase`. Explicit mentions bypass vector retrieval entirely, placing the exact file contents directly into the prompt context for maximum edit fidelity.
3. **Semantic Search (`@codebase`) for Conceptual Inquiries:** Reserve `@codebase` queries for architectural and conceptual questions where exact strings are unknown, such as "Where do we transform webhook payloads before database ingestion?"
4. **Remote MCP Tools for External Specifications:** Use your connected Fast.io MCP server to retrieve external requirements, compliance documents, and API contracts, keeping broad enterprise context separate from local code syntax.

## Frequently asked questions

### What is the maximum codebase size Cursor can index?

Cursor does not publish a rigid hard cap on repository file count, but the indexing engine functions optimally on projects with up to 10,000 source files. Repositories approaching 50,000 to 100,000 files frequently experience indexing degradation, synchronization stalls, and elevated memory usage. In addition, Cursor automatically skips individual files larger than `1 MB` during background vector indexing.

### How do I exclude large files from Cursor indexing?

To exclude large files, create a .cursorignore or .cursorindexingignore file in your repository root. Add glob patterns for heavy assets, such as package lockfiles, build directories, test fixtures, and media files. Cursor automatically respects .gitignore rules by default, but dedicated Cursor ignore files provide finer control over AI context.

### How to query large documentation and files in Cursor without slowing down indexing?

Store large technical documentation, API specifications, and reference manuals in an external intelligent workspace like Fast.io rather than committing them to your git repository. By connecting Cursor to Fast.io through storage for AI agents using the remote MCP server documented at https://mcp.fast.io/docs, Cursor agents search and retrieve documentation on demand without burdening the local indexing engine.

### What is the difference between .cursorignore and .cursorindexingignore?

The .cursorignore file completely blocks Cursor's AI features, including Agent, Chat, Tab, and codebase search, from accessing or reading the specified files. In contrast, .cursorindexingignore prevents files from being added to the background vector index for @codebase queries while still permitting developers to manually reference them in prompts using @file.

### Does Cursor index binary files or PDFs?

No. Cursor's codebase indexing engine only processes plaintext source code and text-based markup files. Non-text binary assets, compiled executables, images, and PDF documents are automatically excluded from the vector embedding index. To query PDFs and unstructured files with an AI assistant, store them in a workspace with document intelligence enabled.

### Why is Cursor stuck on indexing?

Cursor usually gets stuck on indexing when a repository contains tens of thousands of unpruned files, massive single-line minified bundles, or large data fixtures that choke the AST parser. To resolve this, add heavy directories to .cursorignore, open the Codebase Indexing settings in Cursor, delete the existing index, and trigger a clean re-indexing cycle.

## Sources

- [Cursor Blog: Securely indexing large codebases](https://cursor.com/blog/secure-codebase-indexing): Cursor requires at least 80% of repository indexing to finish before semantic search becomes available on large codebases.
- [Cursor Blog: Securely indexing large codebases](https://cursor.com/blog/secure-codebase-indexing): Reusing teammate index structures reduces Cursor's 99th percentile time-to-first-query from 4.03 hours down to 21 seconds.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.