Worktrees and branches. Fleet

Every session gets a real checkout of its own, branched from origin, so agents never share a working directory.

Fleet's isolation model is a git worktree per session. Not a container, not a copy of the repository, not a fork: a second working directory attached to the same repository, on its own branch.

If the idea is new, what a git worktree is explains it from scratch.

What Fleet creates, and when

Nothing on disk exists until you send a session's first prompt. Then, in order:

git fetch for the base branch.
A branch created from origin/<base>.
git worktree add for a checkout at that branch.

Why it fetches and never pulls

The base branch is checked out in your main worktree. Pulling would move your checkout to serve a background session, which is the merge trap wearing a different hat. Fetching only writes remote-tracking refs, so nothing you are looking at changes.

The point of branching from origin/<base> rather than your local base is that an agent should not start work against a week-old main. If the fetch cannot happen, because you are offline, because there is no remote, or because the base is local only, Fleet falls back to the local branch and starts anyway. A session that refuses to start is worse than one that starts from a slightly older base and says so.

Branch names

Branches are prefixed fleet/ and named after what you asked for, which is possible only because the branch is created after the first prompt rather than at session creation.

The gap a fresh worktree leaves

git worktree add gives you tracked files and nothing else. No node_modules, no .env.local, no generated config. Two repository settings close that gap before the agent's first turn:

Included files. Gitignored paths copied in from your main checkout, by glob: .env.local, certs/**. A missing file here is reported and provisioning carries on, rather than failing the session over an optional secret.
The setup script. Runs once, after the worktree exists and before the agent starts. npm install, bundle install, whatever your repository needs.

A setup script that exits nonzero does not fail the session. A worktree whose install failed is still a worktree an agent can read code in, and failing there would discard the prompt already waiting to be delivered. You get a banner and the retained log instead.

What you can do with the checkout

It is an ordinary directory. Open it in your editor with Cmd O, open a terminal in it, run scripts in it. Fleet is not holding it hostage.

Removal, and why it is careful

Worktree removal is idempotent, because a worktree can already be gone: you deleted it in Finder, or a merged pull request reclaimed it. Fleet prunes first, and treats "is not a working tree" as success rather than as a failure that aborts the rest of the cleanup.

Removal is also never forced. Uncommitted work in a worktree is no evidence that the work landed, so a worktree that refuses to go is simply left in place and Fleet says so.

The merge trap

Because the base branch is checked out in your main worktree, git checkout main from a session worktree fails. This is git's rule, not Fleet's. Merges therefore run from the main worktree, one at a time per repository, and refuse rather than stashing anything on your behalf.