Last reviewed: 2026-06-22
Direct answer
Parallel coding-agent worktrees should be cleaned up only after the operator can prove three things: the worktree is tied to the expected branch or commit, the intended changes are captured in a reviewable pull request or handoff note, and the remaining local directory can be removed without losing evidence. Git worktrees are designed to let one repository have multiple working trees attached to it, but that flexibility also makes stale directories and unclear branch ownership easy to miss.
Use this cleanup workflow after each agent run:
- Setup assumptions: the agent worked in a named Git worktree, the main repository remains available, and the operator can run read-only Git inspection commands before removing anything.
- Happy-path request plan: list worktrees, confirm the agent worktree path, confirm the branch or detached commit, inspect status and diff summary, verify the pull request or review note exists, then remove only the confirmed worktree.
- Error-path check: if the worktree has uncommitted files, an unexpected branch, missing review evidence, or a failing workflow run, stop cleanup and record the issue before retrying.
- Minimum assertions: expected path, expected branch or commit, clean or intentionally preserved status, linked review artifact, and CI state recorded from the relevant workflow page.
- Pass/fail logging fields: worktree path, branch, commit, status summary, review link, workflow link, cleanup decision, operator, and timestamp.
- What not to assert: do not claim a merge is safe, a deployment is healthy, or a model-generated change is correct just because the worktree is clean.
For related handoff discipline, see Parallel Worktree Handoffs for Coding Agent Teams .
Who this is for
This guide is for maintainers who run more than one coding agent against the same repository, especially when each agent gets its own branch and worktree. It is also useful for reviewers who need a repeatable checklist before they let an agent-created directory disappear from a shared machine.
Key takeaways
- Treat each worktree as a separate operating surface with its own path, branch or commit, and cleanup decision.
- Confirm Git state before removal because a deleted worktree can leave stale administrative records that later need pruning.
- Tie cleanup to review evidence: a pull request, handoff note, or explicit stop note should exist before the directory goes away.
- Use workflow status as supporting evidence, not as proof that the code is correct.
- Keep the log sanitized and structural so another operator can reconstruct what was checked without exposing secrets or full generated outputs.
Smoke-test workflow
Run the smoke test from the main repository or another trusted worktree.
cleanup_check:
worktree_path: "../agent-task-placeholder"
expected_branch: "agent/example-placeholder"
observed_commit: "<commit-sha-placeholder>"
git_status_summary: "clean | changes-present | unknown"
review_artifact: "<pull-request-or-handoff-link-placeholder>"
workflow_artifact: "<workflow-run-link-placeholder>"
cleanup_decision: "remove | hold | escalate"
reason: "<short-placeholder-reason>"
checked_by: "<operator-placeholder>"
checked_at: "2026-06-22T00:00:00Z"
A passing cleanup check means the worktree can be removed or held with a clear reason. It does not mean the change should be merged, deployed, or trusted without review.
Failure modes
- Evidence gap: the agent cannot inspect the failing log, source page, pull request, or local command output. The safe action is to stop and record the missing evidence instead of guessing.
- Scope drift: the agent edits files that are not connected to the observed failure. Keep the repair tied to the failing signal and leave unrelated cleanup for a separate task.
- 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.
- Unreviewed fallback: the agent changes models, endpoints, permissions, or retry behavior to make a run pass without preserving the review boundary. Treat access and provider failures as operational blockers, not topic failures.
- Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next operator repeat the investigation.
Sources checked
- Git worktree documentation - accessed 2026-06-22; purpose: verify parallel worktree isolation commands and constraints.
- GitHub pull requests documentation - accessed 2026-06-22; purpose: verify pull request review and collaboration boundaries.
- OpenAI Codex AGENTS.md guidance - accessed 2026-06-22; purpose: verify repository instruction-file context for coding agents.
- GitHub Actions documentation - accessed 2026-06-22; purpose: verify workflow runs, jobs, steps, checks, and logs.
Contract details to verify
| Area | What to verify | Source URL | Accessed | Safe candidate wording |
|---|---|---|---|---|
| Worktree inventory | Confirm the current Git reference supports listing, removing, and pruning worktrees. | https://git-scm.com/docs/git-worktree | 2026-06-22 | “List the worktrees before cleanup and remove only the confirmed worktree path.” |
| Stale worktree cleanup | Confirm how stale administrative files are handled when a working tree is deleted outside the normal command path. | https://git-scm.com/docs/git-worktree | 2026-06-22 | “If cleanup happened outside the normal removal flow, check whether pruning is needed.” |
| Review handoff | Confirm the team has a pull request or equivalent review record before deleting local evidence. | https://docs.github.com/en/pull-requests | 2026-06-22 | “Tie cleanup to a reviewable artifact before the directory is removed.” |
| Repository instructions | Confirm which repository instructions applied to the agent run before evaluating the output. | https://github.com/openai/codex/blob/main/docs/agents_md.md | 2026-06-22 | “Record which instruction file governed the agent task.” |
| Workflow evidence | Confirm the relevant workflow run is linked when CI state affects the cleanup decision. | https://docs.github.com/en/actions | 2026-06-22 | “Record workflow evidence as supporting context, not as a merge guarantee.” |
Reader next step
Compare the workflow against Start with CometAPI .
FAQ
Should every parallel agent get its own worktree?
When agents may touch overlapping files or branches, separate worktrees make ownership easier to inspect. The Git reference supports multiple working trees attached to one repository, which fits parallel branch work.
Can I remove a worktree as soon as a pull request exists?
Only if the cleanup log confirms the expected path, branch or commit, status summary, and review artifact. If local files are still uncommitted or unexplained, hold the worktree.
What if the worktree was deleted manually?
Check the Git worktree reference for cleanup and pruning behavior, then record what was found. Do not assume the repository metadata is already tidy.
Does a passing workflow mean the worktree is safe to delete?
A workflow result is useful evidence, but it is not the whole cleanup decision. Pair it with Git status, review handoff, and operator notes.
What should stay out of the cleanup log?
Do not include secrets, real access tokens, full prompts, full generated responses, private customer data, or unsupported claims about production behavior.