Skip to main content
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.
Multi-root workspaces have two limitations:
  • Cline rules only work in the primary workspace folder
  • Checkpoints are disabled (restored when you return to a single folder)
See Current Limitations for details.

​
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: 
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. 
my-company/                    # Single Git repo
├── .git/
├── packages/
│   ├── web/                   # React frontend
│   ├── api/                   # Node.js backend
│   └── shared/                # Common utilities
└── package.json
Multiple Repositories: Separate Git repositories, each with their own history, opened together in one VSCode workspace. 
~/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:
PropertyDescription
PathAbsolute path to the folder
NameDerived from folder name or workspace file
VCS TypeGit, Mercurial, or None
Commit HashCurrent 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.
While Cline detects VCS information for all workspace folders, certain features only use the primary workspace (the first folder): Cline rules, workflows, and Git-related features like @git mentions.

​
Referencing Files Across Workspaces

​
Natural Language References

Cline understands natural references to your workspaces: 
"Read the package.json in the frontend folder"

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

"Search for TODO comments across all workspaces"

​
Workspace Hints Syntax

For explicit references, use the @workspace:path syntax:
SyntaxDescription
@frontend:src/App.tsxFile in the “frontend” workspace
@backend:server.tsFile 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

~/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

~/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

~/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

~/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

  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 to let Cline understand structure first
  • Add a .clineignore file to reduce noise, speed up scanning, and keep Cline focused on source code:
# Dependencies
**/node_modules/

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

# VCS metadata
**/.git/
For more patterns and gotchas, see the .clineignore File Guide.