Skip to main content

​
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

Parallel sessions

Run multiple chats at the same time without them overwriting each other’s file changes.

Safe by default

Each session has a dedicated branch. Nothing lands on main until you decide to merge or open a PR.

Clean rollback

Discard a session’s worktree and its branch disappears with it — no stray commits to clean up.

Isolated tooling

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

# .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.
SituationUse
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 installBoth — 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.