Multi-Root Workspaces - Cline

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.

<Frame> <video src="https://storage.googleapis.com/cline_public_images/multiworkspace.mp4" autoPlay muted loop playsInline controls /> </Frame> <Warning> Multi-root workspaces have two limitations: - **Cline rules** only work in the primary workspace folder - **[Checkpoints](/core-workflows/checkpoints)** are disabled (restored when you return to a single folder)

See Current Limitations for details. </Warning>

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/                  # [email protected]:acme/frontend.git
│   └── .git/
├── backend/                   # [email protected]:acme/backend.git
│   └── .git/
└── contracts/                 # [email protected]: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.

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.

<Note> While Cline detects VCS information for all workspace folders, certain features only use the **primary workspace** (the first folder): [Cline rules](/customization/cline-rules), [workflows](/customization/workflows), and [Git-related features](/core-workflows/working-with-files) like `@git` mentions. </Note>

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:

The name field in your .code-workspace file (if specified)
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 (.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 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

Group related projects that often need coordinated changes
Use a workspace file for reproducible setups across your team
Name folders clearly so workspace hints are intuitive
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 to let Cline understand structure first
Add a .clineignore file to reduce noise, speed up scanning, and keep Cline focused on source code:

text

# Dependencies
**/node_modules/

# Build outputs
**/dist/
**/build/

# VCS metadata
**/.git/

For more patterns and gotchas, see the .clineignore File Guide.