Lesson 14

Multi-root Workspaces

What Multi-root Workspaces Are

A typical Kiro workspace has a single root folder - one project, one .kiro/ directory. A multi-root workspace brings multiple folders into a single IDE window. Each folder is an independent "root" with its own configuration.

You'd use this when working across related but separate projects simultaneously - for example:

An Angular frontend and a Node.js backend in one window
A shared component library and the app that consumes it
A monorepo with multiple packages where each needs different Kiro config

How to Create One

File → Add Folder to Workspace... - adds another root folder
Drag and drop a folder from Finder into the Explorer view
Save as a .code-workspace file to reopen the same multi-root layout later

Why It Matters for Kiro Configuration

Each root folder gets its own .kiro/ directory - its own steering, hooks, skills, agents, specs, and MCP config. This means:

my-workspace/
├── frontend/                    # Root 1
│   └── .kiro/
│       ├── steering/            # Angular-specific steering
│       ├── hooks/               # Frontend-specific hooks
│       ├── skills/              # Frontend skills
│       └── settings/mcp.json    # MCP servers for frontend work
│
├── backend/                     # Root 2
│   └── .kiro/
│       ├── steering/            # Node/Express steering
│       ├── hooks/               # Backend-specific hooks
│       └── settings/mcp.json    # Database MCP, different API servers
│
└── shared-lib/                  # Root 3
    └── .kiro/
        └── steering/            # Library-specific conventions

Each root is configured independently. When you're working in a frontend file, the frontend steering applies. When you switch to a backend file, the backend steering applies.

Scoping Rules

Feature	Scoping in multi-root
Steering	Each folder's `.kiro/steering/` applies to that folder only
MCP servers	Each folder's `.kiro/settings/mcp.json` is independent. Later workspace folders override earlier ones if there's a name conflict.
Hooks	Each folder's `.kiro/hooks/` applies to events in that folder
Skills	Each folder's `.kiro/skills/` is available when working in that folder
Specs	Each folder's `.kiro/specs/` belongs to that project
Global config	`~/.kiro/` applies across ALL folders (as always)

MCP Precedence in Multi-root

MCP configs are merged with this precedence (highest wins last):

Later workspace folders override earlier ones. User-level config has the lowest precedence. Name servers uniquely to avoid collisions.

If your frontend and backend both define a server named "github" with different tokens, the later folder in the workspace order wins. Name servers uniquely to avoid collisions.

Practical tip: Put truly shared MCP servers (GitHub, Jira) in your global ~/.kiro/settings/mcp.json so they work regardless of which folder you're in. Only put folder-specific servers (database for backend, component docs for frontend) in the per-folder config.

When Multi-root Helps vs. When It Doesn't

Good use cases	Better as single-root
Frontend + backend in one window	A monorepo where all code shares conventions
App + shared library development	A single Angular project
Projects that need different MCP servers or steering	Projects that share all configuration
Microservices with independent configs	Tightly coupled code that references across folders constantly

If everything in your workspace uses the same steering, same MCP, same hooks - multi-root adds complexity without benefit. Use it when the roots genuinely need different configuration.

Connection to What You Know

Steering (Lesson 1) - fileMatch patterns work relative to the folder root, not the workspace root. src/app/**/*.ts in folder 1's steering matches folder 1's files only.
Context (Lesson 2) - the active file determines which folder's steering/config is "live" at any moment.
MCP (Lesson 5) - per-folder MCP means your backend can have database access without loading those tool definitions when you're working on frontend.

Your Tangible Win

You understand how multi-root workspaces scope Kiro's configuration per-folder, how MCP precedence works, and when multi-root adds value vs. unnecessary complexity. You can set up a frontend + backend workspace where each root has tailored steering, hooks, and MCP access.

Quiz

You have a frontend folder and a backend folder in a multi-root workspace. You're editing a backend file. Which steering applies?

Both frontend and backend steering combined

The backend folder's steering + global steering

Only global steering - multi-root disables per-folder steering

Where should shared MCP servers (GitHub, Jira) be configured in a multi-root workspace?

In every folder's mcp.json (duplicated)

In global ~/.kiro/settings/mcp.json - available regardless of active folder

In the first folder's mcp.json only

Recommended resources: Multi-root Workspaces.