Use Cursor effectively in a monorepo by configuring .cursorignore to exclude irrelevant packages, opening separate Cursor windows for different sub-projects, using @folder and @file to scope context precisely, and creating per-package .cursor/rules/ that auto-attach. Strategic context management prevents the AI from filling its context window with irrelevant code.
Managing Cursor's Context in Large Monorepos
Monorepos with hundreds of thousands of files overwhelm Cursor's indexing and context window. When the AI has too much context, it becomes slow, inaccurate, and expensive. The core principle is: only send the model what it truly needs, in the sparsest form possible. This tutorial covers every technique for taming Cursor in large codebases: aggressive file exclusion, separate windows, strategic context scoping, and per-package rules.
Prerequisites
- Cursor Pro or Business (needed for larger context windows)
- A monorepo with multiple packages or services
- Understanding of your monorepo's package structure
- Git initialized with proper .gitignore
Step-by-step guide
Configure aggressive .cursorignore exclusions
Configure aggressive .cursorignore exclusions
Create a comprehensive .cursorignore that excludes build artifacts, dependencies, and unrelated packages from Cursor's indexing. Cursor indexes all files not in .gitignore or .cursorignore. In a monorepo, most packages are irrelevant to your current task.
1# .cursorignore — Monorepo exclusions23# Dependencies (critical — these can be millions of files)4node_modules/5.pnpm-store/6vendor/78# Build outputs9dist/10build/11.next/12.turbo/13.nx/14coverage/1516# Generated files17__generated__/18*.min.js19*.bundle.js20*.d.ts.map2122# Large data files23*.csv24*.sql.gz25fixtures/large/2627# Unrelated packages (uncomment when focused on specific packages)28# packages/legacy-app/29# packages/docs-site/30# packages/admin-dashboard/Pro tip: Use .cursorindexingignore instead of .cursorignore for packages you occasionally need. They are excluded from search but still accessible via explicit @file references.
Expected result: Cursor's indexing is limited to relevant source files, dramatically improving performance and context quality.
Open separate Cursor windows for sub-projects
Open separate Cursor windows for sub-projects
For large monorepos, open separate Cursor windows rooted at the package level rather than the monorepo root. Each window indexes independently and has its own context scope. This is the single most effective technique for monorepo performance.
1// Open terminal and launch Cursor for specific packages:2// cursor packages/frontend/3// cursor packages/backend-api/4//5// Each window:6// - Has its own independent index7// - Only sees files in that package8// - Loads .cursor/rules/ from that package9// - Does not waste context on other packages10//11// To reference shared packages, use @file with relative paths:12// @../../packages/shared/types/user.tsPro tip: Create shell aliases for your most-used packages: alias cf='cursor packages/frontend/' and alias cb='cursor packages/backend-api/'
Expected result: Each Cursor window operates on a smaller codebase with faster indexing and more relevant AI suggestions.
Use precise @context scoping in prompts
Use precise @context scoping in prompts
In monorepo prompts, never use @codebase which searches the entire project. Instead, use @folder to scope searches to specific packages and @file for precise file references. This keeps context focused and prevents irrelevant code from consuming the context window.
1// BAD — searches entire monorepo:2// @codebase How does our auth system work?34// GOOD — scoped to specific package:5// @packages/backend-api/src/auth/ How does our auth system work?67// BEST — precise file references:8// @packages/backend-api/src/auth/authService.ts9// @packages/shared/types/auth.ts10// Explain how the auth service validates JWT tokens.Pro tip: When you must search broadly, use Chat (Cmd+L) in Ask mode first to identify the relevant files, then reference those specific files in a follow-up Composer session.
Expected result: AI responses are faster and more accurate because context is limited to relevant files.
Create per-package auto-attaching rules
Create per-package auto-attaching rules
Place .cursor/rules/ directories inside each package with rules specific to that package's technology, conventions, and dependencies. These rules auto-attach based on file location, ensuring the correct context regardless of which monorepo window you use.
1---2description: Frontend package context3globs: "packages/frontend/**"4alwaysApply: false5---67- Framework: Next.js 15 with App Router8- UI: shadcn/ui + Tailwind CSS9- State: Zustand for client state, React Query for server state10- Types: import shared types from @company/shared-types11- Tests: Vitest + React Testing Library12- Do NOT import from packages/backend-api/ directly — use API client13- API client: packages/frontend/src/lib/api.tsExpected result: Package-specific rules auto-attach when editing files in that package.
Use Notepads for cross-package architecture context
Use Notepads for cross-package architecture context
Create Cursor Notepads for architectural documentation that spans multiple packages. Notepads serve as reusable context containers that you reference with @notepad-name when working on cross-cutting concerns. This is more efficient than loading multiple package files.
1// Create a Notepad in Cursor (Ctrl+Shift+J or via sidebar):2// Name: monorepo-architecture3//4// Content:5// ## Package Dependencies6// frontend → shared-types, api-client7// backend-api → shared-types, database8// workers → shared-types, database, queue9//10// ## Shared Contracts11// API types: packages/shared-types/src/api/12// Database models: packages/shared-types/src/models/13// Event types: packages/shared-types/src/events/14//15// ## Inter-Package Communication16// Frontend → Backend: REST API via api-client package17// Backend → Workers: Message queue (BullMQ)18// Workers → Backend: Database writes + event bus1920// Reference in prompts:21// @monorepo-architecture Generate a new API endpoint...Pro tip: Notepads persist across sessions and are referenced on demand with @notepad-name. They are ideal for architecture context that does not change frequently.
Expected result: Cross-package context is available on demand without loading large file trees into the context window.
Complete working example
1# ===========================================2# Monorepo .cursorignore3# Only index source code relevant to current work4# ===========================================56# Dependencies — CRITICAL for monorepo performance7node_modules/8.pnpm-store/9.yarn/10vendor/1112# Build and cache13dist/14build/15.next/16.turbo/17.nx/18.cache/19coverage/20.eslintcache2122# Generated files23__generated__/24*.min.js25*.min.css26*.bundle.js27*.chunk.js28*.d.ts.map29src/**/*.generated.ts3031# Large data files32*.csv33*.sql.gz34*.sqlite35fixtures/large/36seeds/data/3738# DevOps (move to .cursorindexingignore if sometimes needed)39terraform/.terraform/40terraform/state/41helm/charts/4243# Package-specific exclusions44# Uncomment packages you are NOT working on:45# packages/legacy-app/46# packages/docs-site/47# packages/mobile-app/48# packages/admin-panel/4950# Logs and temp51logs/52tmp/53*.logCommon mistakes when using Cursor in a Monorepo
Why it's a problem: Using @codebase in a monorepo
How to avoid: Use @folder scoped to the specific package or @file for precise references. Save @codebase for small, focused projects only.
Why it's a problem: Opening the monorepo root as a single Cursor window
How to avoid: Open separate Cursor windows for each active package: cursor packages/frontend/ and cursor packages/backend/.
Why it's a problem: Not updating .cursorignore as focus shifts between packages
How to avoid: Comment/uncomment package exclusions in .cursorignore as you shift focus. Use .cursorindexingignore for packages you occasionally need.
Best practices
- Open separate Cursor windows for different monorepo packages for independent indexing
- Use .cursorignore aggressively: node_modules, build outputs, generated files, unrelated packages
- Use .cursorindexingignore for packages excluded from search but still accessible via @file
- Scope context with @folder and @file instead of @codebase in monorepo prompts
- Create per-package .cursor/rules/ that auto-attach based on file location
- Use Notepads for cross-package architecture context referenced with @notepad-name
- Start new chat sessions when switching between packages to reset context
- Create shell aliases for quick package-level Cursor window launching
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I have a monorepo with packages: frontend (Next.js), backend-api (Express), shared-types, workers (BullMQ). Generate a .cursorignore file and per-package .cursor/rules/ files that optimize AI code generation for each package independently.
@packages/frontend/src/auth/ @packages/shared-types/src/api/auth.ts Generate an auth middleware for the frontend package. Only use imports available in the frontend package and shared-types. Do not import from backend-api or workers packages.
Frequently asked questions
What is Cursor's context window size?
It depends on the model. Claude 3.5 Sonnet has ~200K tokens (~150K words). In practice, 3-4 large code files plus conversation history fills the window. MAX mode provides larger context but costs more credits. Strategic @file references are more effective than loading entire packages.
How does Cursor handle large codebases efficiently?
Cursor creates embeddings of your codebase for semantic search. Files in .gitignore and .cursorignore are excluded. For monorepos, open separate windows per package, use aggressive .cursorignore, and scope @context to specific folders.
Should I use one Cursor window or multiple for a monorepo?
Multiple. Open separate windows for each active package. Each window indexes independently with its own rules. This is the single most effective monorepo optimization.
How long does Cursor take to index a large monorepo?
A monorepo with 8,800+ files can take 7-12 hours. Reducing indexed files with .cursorignore and opening package-level windows can cut this to minutes. Cursor only auto-indexes folders with fewer than 10,000 files.
Can Cursor search across monorepo packages?
Yes, if you open from the root and all packages are indexed. But this is usually counterproductive. Use precise @file references to specific files in other packages instead of broad cross-package searches.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation