Last reviewed: 2026-07-21
Direct answer
Keep an agent worktree available until the pull request has a recorded outcome: merged, closed without merge, or returned for a follow-up pass with enough branch and review evidence for another operator to continue. A worktree is not just a temporary folder left behind after a coding agent finishes. In a review workflow, it is the local checkout that lets a reviewer inspect the generated diff, rerun a focused command, compare the branch against the base branch, and ask for a small repair without rebuilding the whole workspace from memory.
A useful retention rule is simple: create one dedicated worktree for the agent branch, open the pull request from that branch, keep the worktree clearly labeled while review is active, and remove it only after the review outcome and cleanup decision are written down. Git’s worktree documentation supports the underlying pattern because a repository can have multiple working trees attached to it, and each linked worktree can hold a separate checkout. Git also provides list, lock, remove, prune, and repair commands that matter when teams need predictable cleanup behavior. GitHub pull requests then provide the collaboration surface where branch changes are proposed, reviewed, discussed, updated, merged, or closed.
For the adjacent branch-handoff pattern, see Parallel Worktree Handoffs for Coding Agent Teams . If your team is still deciding when a branch is isolated enough for concurrent agent work, pair this article with Use Git Worktrees to Keep Parallel Coding Agents Isolated .
Smoke-test workflow
Setup assumptions: the agent worked on a dedicated branch, the repository supports Git worktrees, the pull request exists in GitHub, and the local machine can run the smallest relevant project checks without exposing secrets. The worktree path should be named so a reviewer can connect it to the branch or pull request without guessing. The branch should not be reused for unrelated changes while review is active.
Happy-path request plan: list the active worktrees, confirm the branch tied to the pull request is still present, open the pull request, rerun the smallest relevant local check, and verify that the reviewer can map the local branch to the pull request branch. Then inspect local status before making any follow-up edits. If the reviewer asks for a small correction, make it in the same retained worktree, commit it to the same review branch, and update the pull request with a short note that names the command rerun and the result.
Error-path check: simulate a reviewer asking for one small follow-up change after the first review pass. The worktree should still be available, the branch should still be checked out or recoverable, and the operator should not need to reconstruct the agent’s context from memory. If the worktree is missing, stale, or attached to the wrong branch, stop before editing and rebuild the branch evidence from the remote pull request, commit history, and any saved command notes.
Minimum assertions: the worktree path exists, the branch name matches the pull request branch, the pull request is still open or has a recorded outcome, local status is understood before edits, and cleanup has not removed review evidence. The retained worktree should not be treated as proof that the change is correct; it only preserves a reviewable local state.
Pass/fail logging fields:
review_window_id: "<REVIEW_WINDOW_ID>"
worktree_path: "<LOCAL_WORKTREE_PATH>"
branch_name: "<BRANCH_NAME>"
pull_request_url: "<PULL_REQUEST_URL>"
latest_check_command: "<COMMAND_NAME_ONLY>"
latest_check_result: "<PASS_OR_FAIL>"
review_outcome: "<MERGED_CLOSED_OR_FOLLOW_UP_REQUESTED>"
cleanup_decision: "<KEEP_OR_REMOVE>"
notes: "<SHORT_SANITIZED_NOTE>"
What not to assert: do not claim that the pull request is ready to merge only because the worktree exists. Do not infer remote review approval from local files. Do not treat a passing local command as proof that all GitHub checks or reviewer concerns are complete. Do not include credentials, full prompts, private logs, or full response bodies in the handoff note.
Who this is for
This guide is for teams running coding agents in parallel branches where pull request review may happen minutes or days after the agent stops. It is especially useful when reviewers need a local path for inspection, follow-up edits, or reproducing a failed check without asking another agent to recreate the original workspace.
The workflow fits terminal agents, IDE agents, and hosted coding assistants as long as the actual repository state lives in Git and the proposed change goes through pull request review. Tool-specific behavior should still be checked against the current documentation for the agent surface in use. The general retention decision should be based on branch state, pull request state, and review needs rather than on the agent brand.
Key takeaways
- A retained worktree preserves the local branch checkout and makes review follow-up faster.
- Git worktree cleanup should wait for a clear pull request outcome, not just the end of the agent session.
- Lock or label worktrees that should not be pruned while review is active.
- The handoff note should connect the local worktree, branch, pull request, checks, and cleanup decision.
- Cleanup is safe only after the team has recorded whether the branch merged, closed, or needs another focused pass.
- A retained worktree is review support, not merge approval.
Sources checked
Git worktree documentation - accessed 2026-07-21; purpose: verify parallel worktree isolation commands and constraints.
GitHub pull requests documentation - accessed 2026-07-21; purpose: verify pull request review and collaboration boundaries.
Official source evidence 3 - accessed 2026-07-21; purpose: verify source-backed claims for this guide.
Claude Code documentation - accessed 2026-07-21; purpose: verify current terminal-agent documentation location and use it only as general agent workflow context.
Contract details to verify
| Area | What to verify | Source URL | Accessed | Safe candidate wording |
|---|---|---|---|---|
| Worktree isolation | Confirm that Git supports multiple working trees attached to one repository and separate branch checkouts. | https://git-scm.com/docs/git-worktree | 2026-07-21 | “Use a dedicated worktree for each agent branch that needs independent review.” |
| Worktree retention | Confirm list, lock, remove, prune, and cleanup behaviors before building local cleanup rules. | https://git-scm.com/docs/git-worktree | 2026-07-21 | “Keep the worktree until the review outcome is recorded, then remove it through the normal Git worktree cleanup path.” |
| Pull request review | Confirm that pull requests are the review and discussion surface for proposed branch changes. | https://docs.github.com/en/pull-requests | 2026-07-21 | “Tie the local worktree to the branch represented by the pull request.” |
| Agent workflow context | Confirm the agent tool’s current repository workflow guidance before using tool-specific commands. | https://docs.anthropic.com/en/docs/claude-code | 2026-07-21 | “Use tool-specific instructions only after checking the current docs for that tool.” |
Failure modes
- Evidence gap: the reviewer cannot inspect the pull request, branch, local command result, or failing output. The safe action is to stop and record the missing evidence instead of guessing.
- Scope drift: the follow-up edit expands beyond the review request. Keep the repair tied to the observed review comment or check result and leave unrelated cleanup for a separate branch.
- Environment mismatch: the local check uses different versions, credentials, feature flags, or runtime settings than the hosted path. Record the mismatch before treating the result as proof.
- Premature cleanup: the worktree is removed after the first commit or first passing command, leaving the reviewer without a local path for small changes.
- Weak handoff: the final note says the issue is fixed but omits the branch, pull request, worktree path, command name, result, changed files, and remaining uncertainty.
- Branch ambiguity: multiple worktrees or branches have similar names, and the reviewer cannot tell which one belongs to the pull request. Use names that make the branch-review relationship obvious.
Reader next step
Before deleting an agent worktree, write a one-screen retention note for the branch under review. Include the worktree path, branch name, pull request link, latest local status, latest check command name, check result, reviewer request if any, and cleanup decision. If the pull request is still open, mark the cleanup decision as keep. If the pull request has merged or closed, remove the worktree through the normal Git worktree cleanup path and record that the local review state was retired.
Use the same note when handing a review to another operator. The goal is not to preserve every terminal line. The goal is to leave enough state that the next person can answer three questions quickly: which local checkout matches the pull request, what was last verified, and what condition must be true before cleanup is safe. For broader review handoff structure, see How to Hand Off Coding Agent Pull Requests for Review and Write Change Scope Notes Before an Agent Pull Request .
Use Write Change Scope Notes Before an Agent Pull Request as the next comparison point. Keep Agent Memory Review Before Long-Running Tasks nearby for setup and permission checks.
FAQ
How long should a coding agent worktree stay on disk?
Keep it until the pull request has a recorded outcome: merged, closed, or returned for follow-up. If review is still active, keep the worktree available or explicitly document why it is no longer needed.
Should every agent worktree be locked?
Lock the worktree when accidental cleanup would disrupt review, when the worktree lives on storage that may appear unavailable, or when another operator needs an obvious signal that the directory is still in use. A clear name and handoff note may be enough for short review windows.
Can I delete the worktree after CI passes?
Not by default. A passing check is useful evidence, but reviewers may still request local inspection or follow-up changes. Wait for the review outcome, then clean up.
What should the reviewer receive in the handoff?
Give the reviewer the branch name, pull request link, worktree path, current local status, relevant check command names, and the cleanup rule. Keep the note short enough that it can be read before the review starts.
Does this require a specific coding agent tool?
No. The retention rule is based on Git worktree and pull request workflow concepts. Tool-specific setup details should be checked in the current documentation for the agent surface your team uses.