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.
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

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

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.
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.