What’s a multi-root workspace?
Kiro now supports opening multiple project folders inside a single IDE window, while keeping each folder independent. This setup suits monorepos, microservices, shared libraries, or workflows that span several repositories. The feature enables unified search, navigation and refactoring across roots without maintaining multiple IDE windows or workarounds.
Why use multi-root workspaces?
Multi-root is particularly useful when:
- Editing an app and a shared library at the same time
- Maintaining related services (frontend, backend, auth) together
- Working with git submodules or npm/yarn/pnpm workspaces
- Searching, navigating, or refactoring across several projects in one place
Setup
There are two simple ways to add another project folder:
- File → Add Folder to Workspace…, then pick the folder
- Drag and drop a folder into Kiro
Kiro recognizes each added folder as a separate root and loads that root’s .kiro configuration files.
How Kiro handles multiple roots
Kiro keeps each root’s identity while exposing unified controls and context across the workspace.
Specs: one list, multiple sources
All steering files appear together under Workspace in the Agent Steering panel and are tagged with their originating root. When creating a new steering file, Kiro offers three options: root-scoped (e.g., my-app agent steering), global (applies across all roots), or foundation files (establish core workspace context). Files marked “Always Included” load for every root; those with “Conditional Inclusion” only load when the agent is working on files within that root.
Agent hooks: scoped to their home
Hooks are listed collectively but remain tied to their source root. For example, a hook in shared-ui/.kiro/hooks/ triggers only when files in shared-ui change, keeping side effects contained to the intended project.
MCP: unified, with rules
All MCP server definitions from each root are loaded at startup. If multiple roots define an MCP with the same name, the definition from the root that appears last in the workspace takes precedence. To avoid collisions, use distinct prefixes (for example, frontend-github and backend-github). When viewing an MCP config, Kiro prompts to select which root’s configuration to inspect.
Codebase search and context
The #codebase search spans all roots; Kiro indexes source, docs and config files from every root folder. When #file finds duplicates (for example, utils/logger.ts in multiple roots), results include full paths so the correct file can be selected. Line-range queries (for example, #file:src/index.ts:10-25) provide focused context.
Real-world example: cross-project workflows
A typical workflow might be: update a Button component in shared-ui, then update my-app to use a new variant prop. With multi-root workspaces, both my-app and shared-ui open in one workspace, and a single conversation with Kiro can span both roots—updating code, running hooks, and applying specs without switching windows or sessions.
For more background, see the General Availability Launch Blog and the Changelog.
Original source: https://kiro.dev/blog/multi-root-workspaces/
