Worktrees and isolation

Every card that changes code builds in its own git worktree on its own branch, cut from your checkout the moment you approve the plan. Your checkout stays on the branch you left it on, and nothing an agent does reaches it until the card lands.

Why a tree per card

Two agents on one checkout would overwrite each other's files, and a half-finished build would sit in your working copy while you review something else. A worktree gives each card a private copy of the repository that shares the object store with your checkout, so it costs seconds to make and no extra clone to keep. Grid uses git's own worktree mechanism, nothing of its own.

When the tree is cut

Prepare can decline a tree for one card. isolatable: no in the card's front matter runs it in the shared checkout even on a project that isolates; yes, partly and no answer at all each cut one.

The trees live under the workspace state folder, one directory per card and one tree per repository inside it:

~/.grid/<workspace>/worktrees/<card-slug>/<repo>/

The branch is grid/<card-slug>. A card that touches three repositories gets three trees and three branches with the same name, and the cut is all or nothing: if one repository cannot be cut, none are, and the move into Doing is refused with the reason on the tile.

What a fresh tree contains

A worktree starts as a clean checkout of the base commit plus the files a clone would not have. Grid copies the seed files from your checkout into the tree: .env and .env.*, *.pem and *.key certificates, and .claude/settings.local.json. A directory is never a seed. A repository can name its own list with the seed key in its grid.toml section. Grid also installs its hooks and marks the folder trusted for the agent's CLI, so the first prompt runs without a permission dialog.

Dependencies are deliberately not installed. Grid does not guess a package manager, and a tree that needs pnpm install or npm install says so in the agent's first prompt. The agent runs it, in the tree, reaching whatever its own agent settings let it reach: Grid mediates no network access of its own.

Where the base comes from

The base commit is recorded on the card when the tree is cut, and the review shows the diff against exactly that commit.

Landing

Closing a card lands its branch, and what landing means is the project's delivery mode. Where Grid merges, it merges the card branch into the base branch in your checkout with a merge commit instead of a rebase.

Delivery mode is set per project under Delivery, with an override per repository. Whether the agent asks before it commits is a separate switch on the same page.

Grid never resolves a conflict and never overwrites your work. The close is refused, and the card stays in its stage with the reason on the tile, when:

• the tree has uncommitted changes the agent never committed, though untracked build caches do not count: node_modules, .pnpm-store, .turbo, .next, .nuxt, __pycache__, .pytest_cache, .mypy_cache and .ruff_cache as a first path segment,
• your checkout has uncommitted changes of its own,
• your checkout is on a different branch than the one the card branched from,
• the merge conflicts,
• the checkout cannot be read.

A conflict is handed back to the card's own agent. Grid tells the session which files conflict and how to fix it: merge the base into the card's branch in the card's own worktree, keep both sides because the base holds other cards' landed work, commit the merge. Grid then lands the branch itself. If no agent is live and the card is still in Deliver, Grid starts one with that as its first message.

Otherwise, fix the cause and close the card again, or land it from the terminal with grid card land <ref>. Force-closing a card from the board skips landing and leaves the branch and the tree in place.

Unmerged work

A background sweep reads every closed card's branch and marks the ones that never merged with a "branch not merged" chip on the closed tile, so a force-close or an agent that closed its own card cannot lose work quietly. The tree is still there, listed by grid worktree ls, until you land or remove it. The sweep skips projects that deliver by putting the card branch on origin (Push the branch, and the PR and MR modes) because a branch that stays unmerged is the intended result there.

Turning it off

The branchPerCard setting decides the blast radius. The workspace default sits in Settings under General, in the Safety section, and a project or a single repository can override it.

A project with no folder, or a folder that is not a git repository, always runs in place. Every session is told in its first prompt whether it is isolated, partly isolated or working in your checkout, so an agent never assumes a safety it does not have.

From the terminal

grid worktree ls
grid worktree gc [--force]
grid worktree rm <card> [--force]
grid card land <ref>

The list shows each tree with its card and its size on disk. Garbage collection removes orphans, trees whose card is closed or gone, and refuses a tree with uncommitted work unless forced. The daemon has to be running for any of these to write.