Let your agents cleanup after they leave your desk

If you are let multiple agents work in parallel on your code base, you need a way to start an agent session with code isolation. The typical way to do this is by creating separate Git worktrees for each agent. avoids that parallel agents overwrite each other’s files. But the sessions pile up, and so do the worktrees. Each one is a full checkout on your disk.

Until recently I did the cleanup work myself, but now VSCode has a worktree cleanup feature to deal with this.

Why do we need this?

Before this feature, you had two options: do it by hand or ignore it.

By hand meant something like this:

git worktree list
git worktree remove <path>
git worktree prune

That works. But it doesn’t tell you which worktree belongs to which agent session, whether the session is still relevant, or how much space you’ll get back.

Archive, done or delete?

Cleanup builds on how VS Code already finishes sessions. There are three actions:

• Close a chat tab: hides the conversation, nothing is deleted.
• Archive (Chat view) or Mark as Done (Agents window): removes the session from the active list but keeps the conversation.
• Delete: removes the conversation permanently.

When you archive a worktree session, VS Code commits uncommitted changes to the session branch and then removes the worktree folder. The branch and commits stay, so restoring the session re-creates the worktree.

That’s fine for one session. It doesn’t scale to thirty.

Using the worktree cleanup editor

Open the command palette in the VSCode Agents Window and run Chat: Open Worktree Cleanup.

 

Then:

1. Choose an inactivity filter and, if needed, a workspace.
2. Review the selected worktrees. You see the branch, the path and an estimated size for each. Select the ones you want to delete.
3. Click on Clean Up Worktree.

So, what happens when you confirm? Normal cleanup does the following:

• marks the listed sessions as done
• commits non-ignored uncommitted changes to their branches
• schedules the worktree folders for removal

Branches and session history are kept. If you need a session later, restore it and the worktree is re-created.

Remark: Ignored files are not committed. Anything in .gitignore (build output, node_modules, local config) is deleted together with the worktree. Normal cleanup also protects worktrees that are used by other sessions or chats.

The cleanup editor also finds worktrees you’d never find through the sessions list:

• Leftover worktrees from done or archived sessions. Marking a session as done doesn’t guarantee its worktree was removed.
• Managed worktrees without a listed session. These are Git-registered worktrees under the <repository>.worktrees directory. Worktrees you created yourself elsewhere are excluded.

Remark: The sizes are estimates. An unknown size doesn’t mean zero storage, and a failed cleanup doesn’t confirm the worktree is gone. If something fails, use Retry Failed Worktrees.

Automatic cleanup of merged sessions

It even gets better and you have the option to configure automatic cleanup. 

The first checkbox marks a session as done after the given number of days of inactivity. The second checkbox permanently deletes it after a grace period. 

A session is only eligible when it has a merged pull request and no related open pull requests. Automatic cleanup is also more careful than manual archiving. It only removes a worktree if the branch tracks an upstream and has no outgoing commits or uncommitted changes. It never force-removes.

That’s it! Run it once, look at the size of what you get back, and decide if you want it automated.

More information

• Manage agent sessions in VS Code
• Delegate two tasks without mixing their changes
• Branches, Stashes & Worktrees