From feee75b158f2b60153cb20002b01c3f5299a3cc5 Mon Sep 17 00:00:00 2001
From: canvrno <46584286+canvrno@users.noreply.github.com>
Date: Wed, 8 Oct 2025 09:03:04 +0000
Subject: [PATCH] Added multiroot docs (#6597)

Co-authored-by: Kevin Bond <kevin@Kevins-MacBook-Pro.local>
---
 docs/docs.json                        |   1 +
 docs/features/multiroot-workspace.mdx | 131 ++++++++++++++++++++++++++
 2 files changed, 132 insertions(+)
 create mode 100644 docs/features/multiroot-workspace.mdx

diff --git a/docs/docs.json b/docs/docs.json
index 30e317e080..fec87c250e 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -117,6 +117,7 @@
 					"features/drag-and-drop",
 					"features/editing-messages",
 					"features/focus-chain",
+					"features/multiroot-workspace",
 					"features/plan-and-act",
 					{
 						"group": "Slash Commands",
diff --git a/docs/features/multiroot-workspace.mdx b/docs/features/multiroot-workspace.mdx
new file mode 100644
index 0000000000..6b95e9b788
--- /dev/null
+++ b/docs/features/multiroot-workspace.mdx
@@ -0,0 +1,131 @@
+---
+title: "Multiroot Workspace Support"
+sidebarTitle: "Multiroot Workspace"
+---
+
+Cline's Multiroot feature _(experimental - Oct 1 2025)_ works seamlessly with VSCode's multi-root workspaces, letting you manage multiple project folders in a single workspace.
+
+## What is Multiroot Workspace Support?
+
+Instead of being limited to one project folder, Cline can read files, write code, and run commands across all folders in your VSCode workspace. This is helpful when working with monorepos, microservices, or when you're working on related projects simultaneously.
+
+## Getting Started
+
+### Setting Up Multi-Root Workspaces
+
+1. **Add folders to your workspace:**
+   - Use `File > Add Folder to Workspace` in VSCode
+   - Or create a `.code-workspace` file with multiple folder paths
+   - Drag and drop folders to the File Explorer
+   - Select multiple folders when opening a new workspace
+
+2. **Start using Cline** - Cline will automatically detect all your workspace folders and interact with them as needed.
+
+For detailed instructions on setting up multi-root workspaces in VS Code, see [Microsoft's official guide](https://code.visualstudio.com/docs/editing/workspaces/multi-root-workspaces).
+
+### How Cline Handles Multiple Workspaces
+
+Once you have multiple folders, Cline automatically:
+
+- Detects all your workspace folders
+- Works with files across different projects
+- Executes commands in the right context
+- Handles path resolution intelligently
+
+## Working Across Workspaces
+
+### Let Cline explore, or guide it precisely
+
+You can reference different workspaces naturally in your prompts:
+
+```
+"Read the package.json in my frontend folder and compare it with the backend dependencies"
+```
+
+```
+"Create a shared utility function and update both the client and server to use it"
+```
+
+```
+"Search for TODO comments across all my workspace folders"
+```
+
+
+## Common Use Cases
+
+### Monorepo Development
+
+Perfect for when you have related projects in one repository:
+
+```
+my-app.code-workspace
+├── web/          (React frontend)
+├── api/          (Node.js backend)
+├── mobile/       (React Native)
+└── shared/       (Common utilities)
+```
+
+Ask Cline: *"Update the API endpoint in both web and mobile apps to match the new backend route"*
+
+### Microservices Architecture
+
+Manage multiple services from one workspace:
+
+```
+services.code-workspace
+├── user-service/
+├── payment-service/  
+├── notifications/
+└── infrastructure/
+```
+
+### Full-Stack Development
+
+Keep everything together while maintaining separation:
+
+```
+fullstack.code-workspace
+├── client/       (Frontend)
+├── server/       (Backend API)
+├── docs/         (Documentation)  
+└── deploy/       (Scripts & config)
+```
+
+
+### Auto-Approve Integration
+
+Multiroot workspaces work with [Auto Approve](/features/auto-approve):
+
+- Enable permissions for operations within workspace folders
+- Restrict auto-approve for files outside your workspace(s)
+- Configure different levels for different workspace folders
+
+### Cross-Workspace Operations
+
+Cline can complete tasks spanning multiple workspaces:
+
+- **Refactoring**: Update imports and references across projects
+- **Feature development**: Implement features requiring changes in multiple services  
+- **Documentation**: Generate docs referencing code from multiple folders
+- **Testing**: Build & run tests across all workspaces and analyze results
+
+When working with large multiroot workspaces, start in [Plan mode](/features/plan-and-act) to let Cline understand your project structure before making changes.
+
+## Best Practices
+
+### Organizing Your Workspaces
+
+1. **Group related projects** that often need coordinated changes
+2. **Use consistent folder structures** across workspaces when possible
+3. **Name folders clearly** so Cline can understand your project structure
+
+### Effective Prompting & Tips
+
+When working with multiroot workspaces, these approaches work best:
+
+- **Be specific** about which workspace when it matters: *"Update the user model in the backend workspace"*
+- **Reference relationships**: *"The frontend uses the API types from the shared workspace"*
+- **Describe cross-workspace operations**: *"This change needs to be reflected in both the web and mobile apps"*
+- **Scope your searches** when dealing with large codebases: *"Search for 'TODO' in just the frontend workspace"*
+- **Break down large tasks** into workspace-specific operations when possible
+- **Consider excluding large folders** like `node_modules` from your workspace search Scope