Clean the Git Worktree Before Handing Off to an Agent

If you hand a repository to an agent without first clarifying what the main and linked worktrees still hold, the agent may treat someone else’s edits, untracked files, or the wrong branch as its own job. A git worktree agent handoff is not “open a folder”—it is a process that passes a clean (or intentionally dirty-listed) worktree path, branch, and scope.

This post covers only why clean first? · handoff checklist? · how to mark remaining dirty?. git-worktree-agent owns creating isolation; agent-git-status-gate owns the post-turn porcelain gate. Here we only cover cleanup immediately before handoff. No pricing, affiliates, or C++ samples.

Grounding: git-worktree. remove only removes clean worktrees by default; unclean trees need --force. Use list to see path, branch, and locked/prunable state.

Why clean the worktree first?

One-line answer: Linked worktrees share objects and most refs but keep per-worktree HEAD and index. Handing over a dirty tree lets the agent treat another person’s index and untracked files as in-scope—and later git worktree remove will refuse the tree.

Reasons to clean first:

1. The handoff boundary blurs. If the human main worktree still has staged hunks, untracked files, or half-edits, pointing the agent cwd there makes those paths look like commit or delete candidates.
2. Remove and move get blocked. Per the docs, git worktree remove allows only a clean worktree (no tracked modifications, no untracked files) unless you pass -f/--force. Locked worktrees need force twice. Leaving “temporary” dirty trees raises cleanup cost.
3. Duplicate branch checkouts are refused. git worktree add refuses a branch already checked out in another worktree by default (--force is an exception and risky). Before creating a dedicated handoff branch, confirm with list that nothing else holds it.
4. Stale admin files linger. Deleting a folder without remove leaves entries under $GIT_DIR/worktrees until prune. Giving the agent a missing path as cwd fails immediately.

Practical rule: before adding an agent path, settle the human tree with commit, stash, a separate worktree, or delete. “Hand it over and let the agent figure it out” is not a boundary.

What is the handoff checklist?

One-line answer: Before handoff: list → secure a scoped worktree → confirm clean (or allowed dirty) → put path, branch, and bans in the prompt. Naming only a cwd is not a checklist.

Handoff checklist:

Step	Command / artifact	Pass when
1. Map	git worktree list / list --verbose	Know path, HEAD, branch, locked/prunable
2. Dedicated tree	git worktree add -b <branch> <path> [<base>] or add <path> <branch>	One agent path ↔ one branch
3. Cleanliness	git status --porcelain in that path	Empty, or only allowlisted paths
4. Scope	Prompt / AGENTS.md	cwd = absolute path; commit only if git branch --show-current matches
5. Bans	Prompt	No other worktree paths, no direct main commits, no peer-branch checkout
6. Afterward	git worktree remove <path> (after cleanup)	Default remove if clean; clean first if not

Copy-paste handoff block:

Handoff (agent):
- cwd: /abs/path/to/wt-ticket-123
- branch: feat/TICKET-123-agent (must match `git branch --show-current`)
- base: origin/main (already fetched); do not checkout main
- scope: only paths under this worktree; no edits in other worktrees
- dirty policy: porcelain empty before done, OR only paths listed below
- Allowed dirty (if any): (none) | path1 path2
- Do not: git worktree remove/move on other trees; do not --force remove without human

Common create/verify commands:

# Map current worktrees
git worktree list
git worktree list --verbose

# Linked worktree + new branch for the agent
git worktree add -b feat/TICKET-123-agent ../wt-ticket-123 origin/main

# Existing dedicated branch into a new path (if no other worktree holds it)
git worktree add ../wt-ticket-123 feat/TICKET-123-agent

# Cleanliness check right before handoff (in that path)
cd ../wt-ticket-123
git status --porcelain

For throwaway experiments only, the docs’ -d/--detach creates a detached worktree. For longer agent work, a named dedicated branch is easier to track and review.

When finished, remove the linked worktree with git worktree remove <path>. If you only deleted the folder by hand, run git worktree prune from the main (or any) worktree to clear stale admin entries. Use lock/unlock as documented for portable or network mounts.

How do you mark remaining dirty?

One-line answer: Changes that must survive handoff are committed, moved to another worktree/branch, or listed by path in the prompt. Writing “a little dirty is OK” without paths is not marking.

How to mark (priority order):

Method	When	Relation to git-worktree
Finish with a commit	Human chunk is logically done	Easier to add/remove a clean agent tree
Split to another worktree	In-progress human work must not be touched	Keep dirty main; agent gets a clean add path
Stash (exception)	Very short park	Name the stash in the handoff block; default: ban stash pop for the agent
Allowed-dirty list	Only files the agent should continue	Align with Done gate: those porcelain lines only
Intentional untracked	Reports / artifacts	.gitignore or allowlist; do not hide forever with -uno

In the prompt:

Remaining dirty (intentional):
- M  src/api/handler.go     # continue: add auth header check
- ?? artifacts/repro.log    # keep; do not commit unless asked
All other porcelain lines = stop and report.

Do not:

1. Run the agent in a dirty main with only “stash/commit as you like.”
2. Use git worktree remove -f to make handoff “look clean” (data loss).
3. Force the same branch into two worktrees and hand that to an agent.
4. Invent CLI flags. The floor is git worktree subcommands and git status --porcelain.

Bottom line: Handoff = list the map · secure a dedicated worktree/branch · confirm clean (or allowlist) via porcelain · mark leftover dirty by path. Same tools as git-worktree-agent and agent-git-status-gate; different moment (before start, not create-isolation or after Done).

FAQ

How is this different from git-worktree-agent?

That post is how to create linked worktrees to isolate agents. This post is the pre-handoff checklist to clean or split a dirty tree. Same add/list/remove; the question is status before you hand over, not creation alone.

Versus agent-git-status-gate?

That post is a post-turn porcelain pass/fail gate. This post is human cleanup and allowed-dirty marking before start. Both use porcelain; owner and timing differ.

What if remove refuses?

The tree is unclean. Per the docs, clean modifications and untracked files, then remove again—or use --force only when you truly discard. Locked worktrees need force twice. Do not default the agent prompt to “delete with -f if blocked.”

When is prune?

After a linked worktree directory was deleted without remove, to clear leftover $GIT_DIR/worktrees entries. If list shows prunable before handoff, fix path/admin state before setting agent cwd.

Sources

• git-worktree — add/list/remove/prune/lock, clean-remove rule, shared vs per-worktree
• git-status — --porcelain for handoff and Done
• Adjacent: git-worktree-agent (create/isolate), agent-git-status-gate (end gate)