How to Configure Multi-Root Workspaces in Cline

According to JetBrains' State of Developer Ecosystem Survey, 34 percent of developers prefer to organize their codebases as monorepos, a figure that jumps to 45 percent for TypeScript developers. Managing these multi-directory setups in VS Code has historically required separate editor windows or complex config files, but recent tooling changes have simplified this workflow. Many teams split their codebases into microservices, separate frontend and backend folders, or share configurations across multiple independent repositories. Opening a separate editor window for each repository fragments the development workspace. It prevents a developer from running commands across directories, checking shared files, or managing unified tasks.

To support this growing workflow, the Cline extension for VS Code released native support for multi-root workspaces in July 2026, allowing agents to execute cross-root operations. Before this update, an autonomous agent was restricted to working inside a single folder. If a task required modifying a database schema in your backend repository and updating the frontend caller, you had to run separate agent sessions in separate windows. This limitation split the agent's context, leading to repetitive prompts and coordination errors. A multi-root workspace in Cline allows the AI agent to traverse, edit, and run terminal commands across multiple distinct directories or repositories in a single VS Code window.

This unified workspace creates an environment where developers can direct an agent to build full features. However, running an agent locally across several folders introduces data management challenges. If your agent edits files, creates documentation, or runs test suites, these changes are stored only on your local disk. If you switch devices, or if you collaborate with a team, your agent's work remains isolated. Traditional cloud storage services do not provide the indexing or search speed required by AI coding extensions.

To bridge this gap, developers connect local agents to shared cloud environments. A persistent cloud workspace acts as a central repository where humans and AI agents share files, database schemas, and workflows. Instead of keeping files on local disks, you can direct your agent to output its code, documentation, and test reports to a persistent workspace. This keeps your agent's files accessible across devices and allows teammates to review results. Developers can start syncing their workspaces with a 14-day free trial of Fast.io on the pricing page.

VS Code is the dominant editor for developers, with usage rates consistently reported in the 70 percent to 75 percent range in recent years. Configuring a multi-root workspace inside this editor involves grouping your independent folders into a single workspace configuration file. This file, ending with the .code-workspace extension, lists the absolute or relative paths of the directories you want to include.

To build a multi-root workspace configuration, create a file named project.code-workspace in your primary directory. Open this file and define your folders in the JSON structure. A typical setup contains a backend folder, a frontend folder, and a shared module directory.

Follow this configuration structure:

{
  "folders": [
    {
      "name": "backend-api",
      "path": "./backend-service"
    },
    {
      "name": "frontend-app",
      "path": "./frontend-ui"
    },
    {
      "name": "shared-types",
      "path": "./shared-modules"
    }
  ],
  "settings": {
    "cline.allowedCommands": [
      "npm test",
      "npm run build"
    ]
  }
}

After saving this file, open it in VS Code by selecting File, then Open Workspace from File. The editor's File Explorer will display three distinct root folders labeled with the custom names you assigned. Cline reads this active workspace definition upon startup. The agent inherits access to all folders listed in the array. This allows it to check types in your shared directory, run tests in your backend repository, and edit components in your frontend project during a single session.

If you prefer to configure this workspace using the editor's visual interface, select File from the top menu, then click Add Folder to Workspace. Select the target directory from your file dialog and click Add. Repeat this process for each repository you wish to manage. After adding your folders, select File, then Save Workspace As, and name the configuration file. This visual approach creates the same JSON structure as manual editing.

When working inside a multi-root workspace, the agent needs to know which folder contains the files you reference. Traditional relative paths like ./src/index.js become ambiguous because multiple roots might contain identical paths. To prevent path conflicts, the Cline extension introduces a prefixing syntax for cross-root context.

Follow these steps to reference files across different root folders:

1. Locate the custom folder name defined in the folders array of your .code-workspace file.
2. Prefix this name with the @ symbol.
3. Append a colon immediately after the folder name.
4. Add the relative path to the file starting from that specific folder's root.

For example, referencing the user service file inside the backend-api directory requires using this path syntax: @backend-api:/src/services/userService.js

If you need the agent to analyze a React button component in the frontend-app directory, use this syntax: @frontend-app:/src/components/Button.tsx

This syntax tells Cline exactly where to find each file. For example, if you want the agent to update an API endpoint and align the frontend request client, you can write a prompt referencing both files: "Refactor the authentication controller in @backend-api:/controllers/auth.js and update the login component in @frontend-app:/src/components/Login.tsx to match."

By using this prefixing syntax, the agent loads the correct files into its context. It avoids the common error of searching for files in the wrong directory root.

In addition to reading and writing files, Cline executes terminal commands relative to the active folder root. When you run a script or test suite, the agent determines the target folder context based on the prefix of the active file or the workspace name you provide. For example, if you ask the agent to run tests in @backend-api, it will launch a terminal shell with the current working directory set to the backend service folder root. This contextual execution prevents commands from running in the wrong folder, which could otherwise corrupt build artifacts or trigger failing tests in unrelated directories.

Persist Cline multi-root workspaces in the cloud

Manage multiple directories and microservices in one place. Fast.io provides a Model Context Protocol server that exposes persistent storage and automated indexing for your AI agent's edits. Every organization starts with a 14-day free trial.

Start 14-Day Trial

Most articles about AI workspace extensions only focus on single folders and miss detailing how config rules (.clinerules) are scoped globally vs locally in multi-root setups. This is a critical gap. When Cline runs in a single-folder workspace, it automatically scans the root directory for a .clinerules file or a .clinerules folder containing markdown instructions. The agent reads these rules at the start of every task, applying them to its commands and code edits.

In a multi-root workspace, the extension scopes these rules differently. Cline only parses and applies .clinerules located in the primary workspace folder. The primary folder is the first directory listed in the folders array of your .code-workspace configuration. If you define three folders in your workspace, Cline will only look for rules inside the first folder. Any .clinerules files stored in the second or third folders are ignored.

This scoping behavior impacts how you manage instructions:

• Centralize your rules: If your frontend and backend projects have different coding standards, you must merge these guidelines into a single .clinerules file. Save this file at the root of your primary folder. You can use the /newrule command in Cline's chat input to create rule files in the primary root.
• Open separate windows: If your folders have conflicting rules that cannot coexist, you must open them as separate single-root workspaces in separate editor windows. This forces the agent to load the rules local to that folder.
• Scoping rules: Inside your centralized .clinerules file, use folder prefixes to scope instructions. For example, write: "When editing files in the backend-api folder, use ES modules. When editing files in the frontend-app folder, use TypeScript and functional components."

Understanding this rules scoping prevents Cline from writing code that violates your team's style guides.

A unified rules configuration should establish clear boundaries and name-spacing. A typical .clinerules file for a multi-root workspace looks like this:

### Multi-Root Development Rules

#### Backend Service Rules
- Coding style: Use asynchronous patterns and class-based controllers in folder backend-api.
- Database: All database migrations must be written using Knex and stored in the migrations folder.

#### Frontend UI Rules
- Styling: Use component-specific CSS modules inside frontend-app.
- State: Manage shared client state using Redux Toolkit.

By structuring your rules this way, you ensure that the agent has a clear understanding of the architectural boundaries of your project.

To coordinate work between multiple directories and team members, developers connect their local Cline environments to shared cloud storage. Fast.io is a cloud workspace platform for agentic teams, allowing agents and humans to share the same file context. Unlike commodity cloud folders, Fast.io includes a Model Context Protocol (MCP) server that exposes persistent storage and automated indexing.

To configure Cline to connect to your shared workspace, open your cline_mcp_settings.json file. Add the Fast.io server configuration to your MCP servers block:

{
  "mcpServers": {
    "fastio-storage": {
      "type": "streamableHttp",
      "url": "https://mcp.fast.io/mcp/key",
      "headers": {
        "Authorization": "Bearer your_auth_token_here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

This configuration connects the agent to Fast.io's Streamable HTTP endpoint. Connecting to a shared cloud workspace provides key advantages:

• Version History: Every file written to the workspace maintains a version history. If the agent makes a mistake while editing code across multiple root folders, you can review and restore previous versions.
• Intelligence Mode: Fast.io automatically indexes files, enabling semantic search and citation-backed Q&A across the entire workspace.
• Metadata Views: Extract structured data from documents (such as contract terms or invoices) using natural language schemas. Metadata Views support 7 field types: Text, Integer, Decimal, Boolean, URL, JSON, and Date & Time. This structured extraction layer is detailed on the Metadata Views product page and is separate from general search.
• Ownership Handoff: Agent accounts can sign up for a trial, build the workspace, and transfer the organization to a human who joins and starts the trial. The Fast.io platform offers three subscription tiers: the Starter plan at $29/mo, the Business plan at $99/mo, and the Growth plan at $299/mo. Every new organization on Fast.io begins with a 14-day free trial, which requires a credit card to activate. This makes it simple to hand off the codebase and workspace to your clients.

By linking your multi-root workspace to Fast.io, you create an auditable environment where your agent's outputs are stored safely.