Isolated tasks

Why isolate

Two agents in the same folder fight over the same files and the same staging area. One saves while the other reads, one commits what the other wrote, and the result is a tangle nobody can review.

An isolated session uses a git worktree: another folder on disk, another branch, the same repository. Each agent works as if it had a clone of its own, without paying to clone.

Create an isolated session

In the new session dialog, at ⌘⇧S, check Create isolated session. The line underneath says exactly what is about to happen, and it changes with the option: either the session starts from the base branch, or it shares files and branch with the project folder.

With the option checked, the name field appears. Leave it blank and the branch is born as session/ plus a nickname generated from your prompt. A project that is not a git repository does not offer the option, and the session uses the project folder.

Where the branch starts

From the project base branch, if you have set one in settings. Without that, Deck looks in this order: the default branch on the remote, then main, then master.

• It fetches before branching. When the base comes from the remote, the app pulls in what is new before creating the worktree, so it starts from the newest commit. You can turn this off per project.
• A repeated name never overwrites. If the branch already exists, Deck creates a numbered variation instead of touching yours.

Where the folder is created

In Settings, under git and worktrees, you pick the place. The same choice applies to the pull request review folders.

What the folder carries over

A worktree is born with the tracked files of the base branch, and nothing more. That would break any project that depends on node_modules and .env, so Deck brings the ignored files along as filesystem links, without copying.

• Only what git confirms as ignored, and only at the top of the repository.
• An ignored file changes in both places. Since it is a link, editing the main .env shows up in the worktree.
• An untracked file that is not ignored stays behind. If you have loose work in the main folder, that is where it stays.
• On Windows, a folder becomes a junction and a file is copied, because linking a file takes a privilege.

This is configurable per project, in case you prefer a completely clean worktree.

Setup command

Each project can have a command that runs in the freshly created worktree, in the background. That is the place to install dependencies or start whatever the task needs. The log goes to a file inside the folder itself, so you can check it later without guessing.

There is also a cleanup command, which runs before the worktree is removed. If it fails, the removal stops and asks whether to go ahead anyway.

Remove it when you are done

The project page has a worktrees tab listing all of them: the branch, the path, the age and the buttons to open a session, see the changes and remove it. There is also the cleanup for orphans, for when you deleted a folder by hand and git still has the record.

On the session side, archiving offers to remove the worktree and the branch together, and explains that canceling archives only the session and leaves the work on disk. If another session is alive in the same folder, the app does not offer to remove it.

With the worktree ready and the branch full of changes, the next step is reading what was done. That is in Diff and review.