> ## 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.
# Worktrees
> How Fabriqa uses git worktrees to isolate every chat session, and how to configure them for your project.
# Worktrees
A worktree is a linked copy of your git repository checked out in a separate directory on its own branch. When you start a new chat in Fabriqa, it provisions a dedicated worktree for that session — meaning every agentic run has its own isolated filesystem and branch from the start.
Fabriqa ties one session to one worktree. The agent works inside the worktree's directory and commits only to that branch, never directly on your main branch.
## Why Worktrees
Run multiple chats at the same time without them overwriting each other's file changes.
Each session has a dedicated branch. Nothing lands on main until you decide to merge or open a PR.
Discard a session's worktree and its branch disappears with it — no stray commits to clean up.
Dependencies, build artifacts, and environment files are scoped per worktree, so one session's state doesn't bleed into another.
## How Panels Change Per Worktree Chat
Opening a chat in a worktree session changes several panels compared to a standard main-branch chat.
A strip at the top of the chat displays the active worktree path, the branch name (e.g. `fabriqa/worktrees/worktree-session-3`), and the session identifier. This tells you at a glance which isolated context the agent is running in.
Sessions are labeled and grouped by their worktree context in the sidebar and tab bar. Worktree sessions appear with a branch icon to distinguish them from chats running on the main workspace.
The diff view is scoped to the worktree's branch. You see only the changes made inside this session — not unrelated work on other branches or the main workspace.
The integrated terminal opens with its working directory set to the worktree root, not the workspace root. Commands like `npm run dev` or `go build` run in the isolated checkout.
A toast appears when the worktree finishes its post-provision setup (or if setup fails). You can start chatting immediately, but you may want to wait for the success toast before running commands that depend on installed dependencies.
***
## Configuring Your Project
Fabriqa looks for two optional configuration files in your project to customize what happens when a new worktree is provisioned. Place them in a `.fabriqa/` directory at your project root (recommended), or directly at the root if you prefer.
```
your-project/
├── .fabriqa/
│ ├── .worktreeinclude ← files to copy into each new worktree
│ └── .worktreesetup ← script to run after copying
├── src/
└── ...
```
Fabriqa checks `.fabriqa/` first. If no `.fabriqa/` directory exists, it falls back to looking for these files at the project root.
***
## `.worktreeinclude` — Copy Files Into New Worktrees
`.worktreeinclude` lists files and directories that should be copied from your main workspace into every new worktree on creation.
**Format:** gitignore-style glob patterns — one entry per line, `#` for comments.
**Safety rule:** An entry is only copied if it also appears in your `.gitignore`. This prevents accidentally exposing tracked files. If a pattern isn't gitignored, Fabriqa skips it silently.
### When to use it
Use `.worktreeinclude` for files that:
* Must exist for the project to start (`.env`, `.env.local`)
* Improve the development experience but are gitignored (`.vscode/`, `.idea/`)
* Are generated locally and not committed (auth tokens, local TLS certs)
These are *static files* — they're copied once at provision time and don't need to be installed or built.
### Example — e-commerce project
```
# .fabriqa/.worktreeinclude
#
# Files to copy into new worktrees (gitignore-style patterns).
# Only entries also present in .gitignore are copied.
# Local environment config — contains DB connection strings, API keys, etc.
.env
.env.local
# VS Code workspace settings and recommended extensions
.vscode/
# Stripe CLI local config (developer machine only, never committed)
.stripe/
```
Only list files that are already in `.gitignore`. Entries that are tracked by git are ignored by the safety check and will not be copied.
***
## `.worktreesetup` — Run Setup Commands After Provision
`.worktreesetup` is a shell script that Fabriqa executes inside the new worktree after file copying completes. Use it for anything that needs to *run* — installing packages, generating code, seeding a local database.
**Execution:** runs via `sh` in the worktree directory, asynchronously with a 5-minute timeout.
**Result:** Fabriqa emits a notification toast when the script finishes. If it times out or exits with an error, you'll see a failure toast.
### When to use it
Use `.worktreesetup` for operations that:
* Install dependencies (`npm install`, `pip install`, `go mod download`)
* Generate code or type definitions from schemas
* Initialize a local database or run migrations
* Build assets needed before the dev server can start
These are *active commands* — they produce output or side effects that the worktree needs to function.
### Example — e-commerce project
```bash theme={null}
# .fabriqa/.worktreesetup
#
# Post-provision setup for the storefront monorepo.
# Runs inside the new worktree after .worktreeinclude files are copied.
# Install dependencies for each package
npm install --prefix packages/storefront
npm install --prefix packages/api
npm install --prefix packages/admin
# Generate TypeScript types from the GraphQL schema
npm run codegen --prefix packages/storefront
# Run database migrations against the local dev DB
npm run db:migrate --prefix packages/api
```
The script runs with the worktree directory as its working directory. Relative paths in your script resolve from the worktree root.
***
## Choosing the Right File
Both files are optional and independent. Use neither, one, or both depending on what your project needs.
| Situation | Use |
| --------------------------------------------------------------- | --------------------------------------------------- |
| You have a `.env` the agent needs to read | `.worktreeinclude` |
| You have IDE settings you want shared across sessions | `.worktreeinclude` |
| You need `npm install` or `pip install` to run in each worktree | `.worktreesetup` |
| You generate types from an API schema on setup | `.worktreesetup` |
| You need `.env` **and** `npm install` | Both — include copies the file, setup installs deps |
For most projects: put gitignored config files in `.worktreeinclude` and all install/build commands in `.worktreesetup`. The include step runs first, so your `.env` is in place before the setup script executes.
***
## Worktree Policy Settings
Worktree behavior can be configured per workspace in **Workspace Settings**:
* **Enable or disable worktrees** for a specific workspace (override the app default)
* **Set the new chat default mode** — whether new chats open in a worktree or on the main branch by default
* **Completion action** — whether finishing a session suggests merging back or opening a PR
These controls let teams adopt worktrees incrementally: enable them for feature work, keep a workspace on main-only mode for quick fixes, or enforce worktrees for all sessions on critical repositories.