Worktrees & env files
Every off-main session runs in its own git worktree, and Plexus copies the env files it needs in as the worktree is created.
Where worktrees live
When you start a session, Plexus cuts a git worktree from the base branch you picked. By default it lands at:
<project>/worktrees/<session-name>
The subfolder comes from worktree.location (default worktrees); the session name is slugified and appended automatically. The value is always a relative path under the project root — it can never escape it. Root-tree sessions don't get a worktree; they run directly in the project's root working tree. See Sessions for the full lifecycle.
Auto-gitignore
When a worktree is created inside the repo, Plexus adds its parent folder to the repo's .gitignore so worktree contents never surface as untracked changes. This is worktree.autoGitignore (default on). Leave it on unless you're managing the ignore entry yourself.
Why env files need copying
A fresh worktree is a clean checkout — it holds only tracked files. Anything gitignored, most importantly .env and .env.local, is not carried over. A dev server or test runner that reads those files would break the moment the agent runs it inside the worktree.
So as each worktree is created, Plexus copies the paths you configure into it — regardless of .gitignore.
Copying paths into worktrees
Two settings control the copy:
| Setting | Default | What it does |
|---|---|---|
worktree.copyEnabled | on | Whether to copy any paths into a new worktree |
worktree.copyPaths | .env, .env.local | The files and folders to copy |
Out of the box, .env and .env.local land in every new session worktree.
Adding paths
- Open Settings and go to the Worktrees category.
- Make sure Copy files into new worktrees is on.
- Add each file or folder you want copied to the paths list, using the add/remove controls.
Paths are relative to the project root and copied as-is whether or not git tracks them; folders are copied recursively. Common additions are .env.development, a local config/ folder, or service-account credentials that live outside version control. Like any setting, these layer per scope — set a baseline globally and override it for one project.
Path safety
Plexus validates every copy path so a worktree can't be corrupted or used to escape the repo:
- Absolute paths and
..traversal are rejected. .and empty entries are rejected.- Symlinks are skipped — a top-level symlink copies nothing, and symlinks inside a copied folder are skipped — so the copy can't leak files from outside the repo.
- Missing sources are silently skipped, so a path that doesn't exist in a given project won't fail the launch. A path that disappears mid-copy — e.g. a tool rewriting
.envat that instant — is skipped the same way rather than failing the launch. A genuine error (an unreadable file, a full disk) still stops the launch, but the message names the exact path so you know what to fix.
Plexus does not auto-assign or remap dev-server ports. If two sessions' dev servers bind the same port, that conflict is yours to resolve — read a port from the .env you copy in, or set one from a hook.