Cursor Multi-Repo

Overview

Configure multi-root workspaces so Cursor sees only repositories and files needed for the task, preserving repository ownership and context boundaries.

Prerequisites

• Explicit authorization for each repository and a data-classification review for shared roots.
• Reviewed rules and ignore files in each root; only necessary filesystem permissions.

Instructions

1. Start with one repository, add another root only for a defined cross-repository task, and remove it afterward.
2. Use repository-specific rules/ignore files and verify indexing scope before asking a cross-repo question.
3. Keep changes separated by repository and use each repository's normal review and test process.

Output

• A deliberately scoped multi-root workspace with documented context and ownership boundaries.

Error Handling

| Condition | Safe response | |---|---| | Unrelated repository appears in context | Remove the root, start a new chat, and verify indexing scope. | | Rules conflict across roots | Apply the most restrictive relevant rule and resolve the conflict through repository owners. | | Memory/indexing becomes slow | Close inactive roots rather than disabling ignore or security controls. |

Examples

To change an API contract and its client, open only those two repositories, attach the contract file explicitly, and create separate reviewed commits. Close the client root when the cross-repo validation is complete.

Work with multiple repositories and monorepo structures in Cursor. Covers multi-root workspaces, selective indexing, cross-project context, and rule inheritance patterns.

Multi-Root Workspaces

Open multiple project roots in a single Cursor window:

Creating a Workspace

1. Open first project: File > Open Folder > select project A
2. Add second project: File > Add Folder to Workspace... > select project B
3. Save workspace: File > Save Workspace As... > mywork.code-workspace

Workspace File Structure

json
// mywork.code-workspace
{
  "folders": [
    { "path": "/home/dev/api-service" },
    { "path": "/home/dev/web-frontend" },
    { "path": "/home/dev/shared-lib" }
  ],
  "settings": {
    "editor.tabSize": 2,
    "files.exclude": {
      "**/node_modules": true,
      "**/dist": true
    }
  }
}

Open workspace: cursor mywork.code-workspace or double-click the file.

How Indexing Works with Multi-Root

• Each folder root is indexed independently
• @Codebase searches across all open roots
• @Files paths include the root name: @api-service/src/routes/users.ts
• Closing a folder removes it from the index

Monorepo Patterns

Opening Full Monorepo

bash
cursor /path/to/monorepo

Pros: @Codebase searches everything, cross-package references work naturally Cons: Slow indexing on large monorepos, lots of irrelevant search results

Focused Opening (Recommended)

bash
# Open just the package you're working on
cursor /path/to/monorepo/packages/api

Pros: Fast indexing, focused search results Cons: No automatic cross-package context

Hybrid: Focused + Selective .cursorignore

bash
# Open the monorepo root but exclude what you don't need
cursor /path/to/monorepo

gitignore
# .cursorignore at monorepo root
# Only index packages you're actively working on

# Exclude everything in packages/
packages/*/

# Except the ones you want indexed:
!packages/api/
!packages/shared/

# Always exclude
node_modules/
dist/
build/
.turbo/

This indexes only packages/api/ and packages/shared/, keeping search focused.

Cross-Project Context

Referencing Files Across Roots

In a multi-root workspace, use the root folder name as prefix:

@api-service/src/types/user.ts @web-frontend/src/hooks/useAuth.ts

The User type in the API doesn't match the frontend hook.
Show me the differences and suggest how to share the type.

Sharing Types Between Projects

Use project rules to guide cross-project imports:

yaml
# .cursor/rules/monorepo-imports.mdc (in monorepo root)
---
description: "Monorepo import conventions"
globs: ""
alwaysApply: true
---
# Import Rules
- Shared types: import from @myorg/shared (never relative paths across packages)
- Shared UI: import from @myorg/ui
- Never import directly from another app package (apps/api → apps/web is forbidden)
- Each package declares its own dependencies in package.json

Rules Inheritance

Monorepo: Root + Package Rules

monorepo/
├── .cursor/rules/
│   ├── global.mdc              # alwaysApply: true (applies everywhere)
│   └── security.mdc            # alwaysApply: true
├── packages/
│   ├── api/
│   │   └── .cursor/rules/
│   │       └── api-patterns.mdc  # Scoped to api/ files
│   ├── web/
│   │   └── .cursor/rules/
│   │       └── react-patterns.mdc  # Scoped to web/ files
│   └── shared/

Behavior:

• Root rules apply to all files in the monorepo
• Package-level rules apply only when editing files in that package
• If both match, both are included in context

Multi-Root: Independent Rules

In a multi-root workspace, each root has its own .cursor/rules/:

# Workspace contains:
api-service/
  .cursor/rules/express-patterns.mdc    # Only applies to api-service files

web-frontend/
  .cursor/rules/react-patterns.mdc      # Only applies to web-frontend files

Rules do NOT cross workspace roots. Each project's rules are independent.

Selective Indexing Strategies

Strategy 1: Single Package Focus

bash
cursor packages/api/
# Only indexes packages/api/
# Fast, focused, no cross-package noise

Strategy 2: Related Packages

gitignore
# .cursorignore at monorepo root
packages/*/
!packages/api/
!packages/shared/
!packages/config/

Strategy 3: Full Monorepo with Heavy Exclusions

gitignore
# .cursorignore
node_modules/
dist/
build/
.turbo/
.next/
coverage/
*.lock
*.min.js
**/*.test.ts       # Optional: exclude tests from indexing
**/fixtures/       # Test fixtures
**/migrations/     # Database migrations (reference via @Files)

Performance Optimization

Memory Management

Each open workspace root consumes memory for indexing. Minimize open roots:

# Instead of opening 5 repos:
cursor repo1/ repo2/ repo3/ repo4/ repo5/   # Heavy

# Open only what you need:
cursor repo1/                                # Light
# Add repo2/ only when needed via File > Add Folder

Large Monorepo Tips

1. Use .cursorignore aggressively
2. Open specific packages, not the root
3. Close workspace folders you're not actively editing
4. Start new chats when switching between packages
5. Use @Files for cross-package references instead of @Codebase

Enterprise Considerations

• Repository access: Multi-root workspaces respect filesystem permissions. Cursor cannot index repos the user cannot read.
• Indexing scope: Only open workspace folders are indexed. Opening a shared drive or network mount may be slow.
• Rule governance: In monorepos, root-level rules serve as team-wide governance. Package-level rules add specificity.
• CI alignment: .cursor/rules/ should be reviewed in PRs like any other configuration change.

Resources

• VS Code Multi-Root Workspaces
• Codebase Indexing
• Cursor Rules