Cursor Multi RepoSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: cursor-multi-repo
description: 'Work with multiple repositories in Cursor: multi-root workspaces, monorepo
  patterns, selective indexing,

  and cross-project context. Triggers on "cursor multi repo", "cursor multiple projects",
  "cursor monorepo",

  "cursor workspace", "multi-root workspace".

  '
allowed-tools: Read, Write, Edit, Bash(cmd:*)
version: 1.19.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- cursor
- cursor-multi
compatibility: Designed for Claude Code
---
# 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 Strategie

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.