> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fabriqa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-project workspaces

> Work with multiple repos or folders inside one Fabriqa workspace, attach projects, and start chats in the right project context.

Fabriqa workspaces can contain more than one project. You can open one folder as your workspace, then attach additional repos or folders so they all live under the same workspace and sidebar.

This is the right setup when you work across a backend repo and a frontend repo, keep infrastructure code beside an app repo, or want one AI workspace for several related codebases.

## What a multi-project workspace is

In Fabriqa, a workspace is the top-level container. Inside that workspace, you can have one or more attached projects.

* A project can be a git repository or a regular folder.
* One project becomes the primary project for the workspace.
* Chats and sessions are grouped under their project in the sidebar.
* New chats can be started for a specific project instead of the workspace as a whole.

## Open a workspace and attach more projects

<Steps>
  <Step title="Open your first folder">
    Use **Open Folder** to create or enter a workspace from a local folder.
  </Step>

  <Step title="Add another project">
    In the sidebar project tree, click **Add project** to attach another repo or folder to the current workspace.
  </Step>

  <Step title="Review detected projects">
    Fabriqa scans the selected path and shows detected candidates before continuing.
  </Step>

  <Step title="Choose what to attach">
    Select the repos or folders you want. Fabriqa supports recommended selections and skips duplicates that are already attached.
  </Step>
</Steps>

## Discovery and selection behavior

When you open or attach a folder, Fabriqa can inspect the path and detect multiple candidates.

* Git repositories are identified separately from plain folders.
* Linked worktrees are detected as their own candidate type.
* Fabriqa can preselect recommended paths for faster setup.
* If a path is already attached, Fabriqa skips it instead of attaching it twice.
* If a folder needs deeper inspection, the discovery flow can continue with a deeper scan.

## How the sidebar organizes projects

When a workspace has attached projects, the sidebar switches from a flat chat list to a project tree.

* Projects are shown as separate groups.
* The primary project stays at the top.
* Git repositories are prioritized ahead of plain folders.
* Each project shows its own main session and any linked worktree sessions.
* Chats stay grouped under the session and project they belong to.

This makes it easier to keep context separated when several repos are part of the same workflow.

## Start chats in the right project

Fabriqa creates chats against sessions, and sessions are tied to a specific attached project.

* If a project already has a main session, Fabriqa reuses it.
* If not, Fabriqa creates a new main session for that project.
* If worktrees are enabled and the project supports them, you can start either a main chat or a linked worktree chat for that project.
* Project-scoped chats keep file access, terminal runs, and git context aligned with the correct path.

## Primary project behavior

Every workspace has a primary project.

* If the workspace explicitly marks a project as primary, Fabriqa uses that one.
* Otherwise, Fabriqa prefers a project whose source is marked as `origin`.
* If neither exists, Fabriqa falls back to the first attached project.

The primary project is used as the default when Fabriqa needs a workspace-level fallback, such as choosing a default main session.

## What happens when a project is missing

Fabriqa keeps track of whether attached project paths still exist on disk.

* If some attached projects are missing, the workspace still opens and shows which projects are unavailable.
* If all attached projects are unavailable, Fabriqa warns that the workspace cannot be used until you reattach a project or open a new folder.
* Workspace summaries show whether projects are ready, missing, or unavailable.

## Good use cases

* A frontend repo and backend repo that ship together.
* An application repo plus a shared design system repo.
* An app repo plus infrastructure or deployment config.
* A monorepo-adjacent setup where related repos stay separate but you want one workspace.

## When to use worktrees instead

Multi-project workspaces and worktrees solve different problems.

* Use a multi-project workspace when you want several repos or folders available in one place.
* Use a linked worktree when you want an isolated branch-based session for one repository.

If you need both, Fabriqa supports that too: each attached git project can still create linked worktree chats when worktrees are enabled.

<CardGroup cols={1}>
  <Card title="Related: Git Worktrees" icon="git-branch" href="/desktop/worktrees">
    Learn how linked worktree chats create isolated branch-based sessions inside a project.
  </Card>
</CardGroup>