# Multi-Root Workspaces

> Cline works with VSCode's multi-root workspaces, letting you manage multiple project folders or repositories in a single…

- 网址：https://funcoding.ai/agents/cline/features/multiroot-workspace/
- 来源：Cline 官方文档原文（英文），Apache-2.0 许可，同步于 2026-10-11
- 官方原文：https://docs.cline.bot/features/multiroot-workspace

---
Cline works with VSCode's multi-root workspaces, letting you manage multiple project folders or repositories in a single window. Whether you're working with a monorepo or separate Git repositories, Cline can read files, write code, and run commands across all of them.

<video
  src="https://storage.googleapis.com/cline_public_images/multiworkspace.mp4"
  autoPlay
  muted
  loop
  playsInline
  controls
/>

<div class="callout callout-warning">

Multi-root workspaces have two limitations:
- **Cline rules** only work in the primary workspace folder
- **[Checkpoints](https://funcoding.ai/agents/cline/core-workflows/checkpoints/)** are disabled (restored when you return to a single folder)

See [Current Limitations](#current-limitations) for details.

</div>

## Understanding Multi-Root Workspaces

Before diving in, it helps to understand the two common patterns for organizing related projects.

### Why Use Multi-Root Workspaces?

Cline can complete tasks that span multiple projects or repositories:

- **Refactoring**: Update an API contract and fix all consumers across repos
- **Feature development**: Implement a feature that touches frontend, backend, and shared code
- **Dependency updates**: Coordinate version bumps across related projects
- **Documentation**: Generate docs that reference code from multiple repositories

**Example prompt:**
```text
Update the User type in the contracts repo, then update both the frontend 
and backend to use the new fields. Make sure the API validates the new 
required field.
```
## Setting Up a Multi-Root Workspace

### Monorepos vs Multiple Repositories

**Monorepo**: One Git repository containing multiple projects or packages. All code shares the same version history.

**Multiple Repositories**: Separate Git repositories, each with their own history, opened together in one VSCode workspace.

```text
~/projects/
├── fullstack.code-workspace   # Workspace config file
├── frontend/                  # git@github.com:acme/frontend.git
│   └── .git/
├── backend/                   # git@github.com:acme/backend.git
│   └── .git/
└── contracts/                 # git@github.com:acme/api-contracts.git
    └── .git/
```

Cline supports both patterns, as well as hybrid setups where some folders are Git repositories and others are not. The key difference: with multiple repositories, each folder has its own `.git` directory and Cline tracks them independently.

### Adding Folders to Your Workspace

You can add folders to your workspace in several ways:

- **File menu**: Use `File > Add Folder to Workspace` in VSCode
- **Drag and drop**: Drag folders directly into VSCode's file explorer
- **Workspace file**: Create a `.code-workspace` file (recommended for teams)
- **Command palette**: Run `Workspaces: Add Folder to Workspace`

For detailed instructions, see [Microsoft's multi-root workspace guide](https://code.visualstudio.com/docs/editor/multi-root-workspaces).

## Working with Multiple Repositories

When you open separate Git repositories in one workspace, Cline treats each as an independent project with its own version control.

### What Cline Tracks Per Repository

For each workspace folder, Cline detects:

| Property | Description |
|----------|-------------|
| **Path** | Absolute path to the folder |
| **Name** | Derived from folder name or workspace file |
| **VCS Type** | Git, Mercurial, or None |
| **Commit Hash** | Current HEAD commit (for Git/Mercurial repos) |

This means Cline understands that your frontend and backend might be at different commits, on different branches, or even use different version control systems.

<div class="callout callout-note">

While Cline detects VCS information for all workspace folders, certain features only use the **primary workspace** (the first folder): [Cline rules](https://funcoding.ai/agents/cline/customization/cline-rules/), [skills](https://funcoding.ai/agents/cline/customization/skills/#triggering-skills-with-slash-commands), and [Git-related features](https://funcoding.ai/agents/cline/core-workflows/working-with-files/) like `@git` mentions.

</div>

## Referencing Files Across Workspaces

### Natural Language References

Cline understands natural references to your workspaces:

```text
"Read the package.json in the frontend folder"
```

```text
"Compare the user model in backend with the TypeScript types in contracts"
```

```text
"Search for TODO comments across all workspaces"
```

### Workspace Hints Syntax

For explicit references, use the `@workspace:path` syntax:

| Syntax | Description |
|--------|-------------|
| `@frontend:src/App.tsx` | File in the "frontend" workspace |
| `@backend:server.ts` | File in the "backend" workspace |
| `@contracts:types/` | Folder in the "contracts" workspace |

This syntax is especially useful when:
- Multiple workspaces have files with the same name
- You want to be explicit about which project you mean
- Cline needs to resolve ambiguity

### How Workspace Names Work

Workspace names are derived from:
1. The `name` field in your `.code-workspace` file (if specified)
2. The folder name (default)

If two folders have the same name, append numbers or use the workspace file to give them unique names.

## Common Configurations

### Monorepo Development

```text
~/projects/my-app/
├── my-app.code-workspace      # Workspace config file
├── web/          (React frontend)
├── api/          (Node.js backend)  
├── mobile/       (React Native)
└── shared/       (Common utilities)
```

All folders share one Git history. Changes across packages are atomic.

**Example prompt:** *"Update the API endpoint in both web and mobile apps to match the new backend route"*

### Microservices with Separate Repos

```text
~/projects/services/
├── services.code-workspace    # Workspace config file
├── user-service/       (git: github.com/acme/user-service)
├── payment-service/    (git: github.com/acme/payment-service)
├── gateway/            (git: github.com/acme/api-gateway)
└── proto/              (git: github.com/acme/service-protos)
```

Each service has its own repository. Cline can update the proto definitions and regenerate clients across all services.

**Example prompt:** *"Add a new field to the UserProfile message in proto, then update user-service and gateway to handle it"*

### Full-Stack with Shared Contracts

```text
~/projects/fullstack/
├── fullstack.code-workspace   # Workspace config file
├── client/         (git: github.com/acme/web-client)
├── server/         (git: github.com/acme/api-server)
└── types/          (git: github.com/acme/shared-types)
```

The types repository defines interfaces used by both client and server. When you update a type, Cline can fix both consumers.

### Hybrid Setup

```text
~/projects/project/
├── project.code-workspace     # Workspace config file
├── main-app/       (git: github.com/acme/main-app)
├── vendor/         (no VCS - vendored dependencies)
└── scripts/        (no VCS - local automation)
```

Mix of repositories and plain folders. Cline adapts to each folder's configuration.

## Current Limitations

Two features have limitations in multi-root workspace mode:

### Cline Rules

[Cline rules](https://funcoding.ai/agents/cline/customization/cline-rules/) (`.clinerules/` directory) only work in the **primary workspace** (the first folder in your workspace). Rules in other workspace folders are ignored.

**Workaround:** Place shared rules in the primary workspace, or use global rules (`~/Documents/Cline/Rules/`) which apply everywhere.

### Checkpoints

[Checkpoints](https://funcoding.ai/agents/cline/core-workflows/checkpoints/) are disabled in multi-root workspace mode. Cline displays a warning when this happens.

**Why:** Checkpoints use a shadow Git repository to track changes. With multiple repositories, coordinating checkpoints across independent Git histories adds complexity that isn't yet supported.

**Workaround:** Use your normal Git workflow. Commit frequently, or create branches for experimental work.

Both limitations are restored when you return to a single-folder workspace.

## Best Practices

### Organizing Your Workspaces

1. **Group related projects** that often need coordinated changes
2. **Use a workspace file** for reproducible setups across your team
3. **Name folders clearly** so workspace hints are intuitive
4. **Consider the primary workspace** for Cline rules placement

### Effective Prompting

- **Be specific** when it matters: *"Update the user model in the backend workspace"*
- **Reference relationships**: *"The frontend uses types from the contracts workspace"*
- **Describe cross-workspace changes**: *"This needs to update both web and mobile"*
- **Scope searches** for large codebases: *"Search for 'TODO' only in the frontend workspace"*

### Working with Large Workspaces

- Break large tasks into workspace-specific operations when possible
- Use [Plan mode](https://funcoding.ai/agents/cline/core-workflows/plan-and-act/) to let Cline understand structure first