What
- Job/session deletion logic now supports an explicit force-remove path for a worktree's directory, used when the normal removal (via git or the WorktreeRemove hook) can't clean it up.
- Before force-removing, Claude Code checks for nested git repositories, tracked (not just uncommitted) changes, and verifies the worktree is actually registered in git's own worktree list; the worktree-state check now separately reports
trackedChanges(real edits) versus plaindirty(which includes untracked files). - If removal is still withheld, the reason is one of
tracked_changes,nested_repositories,nested_unverified, ornot_registered, and a newaFtmessage generator produces detailed explanations for every possible refusal reason (dirty, unpushed, unpushed_shared, in_use, live_lock, occupied, shared_record, records_unreadable, unverified, identity_changed, and the remove_failed sub-reasons above). - The
claude rmCLI command gains two new flags:--discard-unpushed <commit>@<worktree-id>to discard unpushed/uncommitted changes on a worktree still at a given commit, and--force-remove-worktree <worktree-id>to force-delete a worktree directory. - The fleet view's job-delete action gained a second confirm-and-retry path for force-removing a worktree (alongside the existing 'discard unpushed changes' offer), and reports whether the branch was preserved.
- Deletion telemetry and results now distinguish a forced removal from the existing 'left worktree in place' outcome, via a new
worktree_force_removedevent and aforcedWorktreeRemoval/forceRemoveWithheldresult field.
Why
Worktrees (the separate folders git uses for each session's checkout) can get stuck when git or a cleanup hook can't remove them, blocking session/job deletion. This gives users and the CLI an explicit, safety-checked way to force the removal through instead of leaving orphaned directories behind, while refusing to blow away directories with nested repos or real tracked changes without being told to.
Names in the bundleclaude rm
claude rm
CLI reference modified, high confidence
| `claude rm <id>` | Remove a [background session](/docs/en/agent-view#manage-sessions-from-the-shell) from the list. Accepts `--discard-unpushed <commit>@<worktree-id>` to discard the worktree and its commits; when a [delete is refused ov…see the edit
--discard-unpushed
CLI reference modified, high confidence
| `claude rm <id>` | Remove a [background session](/docs/en/agent-view#manage-sessions-from-the-shell) from the list. Accepts `--discard-unpushed <commit>@<worktree-id>` to discard the worktree and its commits; when a [delete is refused ov…see the edit
claude rm
Manage multiple agents with agent view modified, high confidence
* Delete the session again to remove the directory anyway, by pressing `Ctrl+X` twice on its row in agent view or running the `claude rm <id> --force-remove-worktree <worktree-id>` command that the `claude rm` refusal printed. Claude Code …see the edit
--force-remove-worktree
Manage multiple agents with agent view modified, high confidence
* Delete the session again to remove the directory anyway, by pressing `Ctrl+X` twice on its row in agent view or running the `claude rm <id> --force-remove-worktree <worktree-id>` command that the `claude rm` refusal printed. Claude Code …see the edit
--discard-unpushed
Manage multiple agents with agent view modified, high confidence
| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | Delete a session whose delete was refused over unpushed commits, discarding the worktree along with its branch and commits. Pass the exact value that refusal printed; see [What…see the edit
claude rm
CLI reference modified, high confidence
| `claude rm <id>` | Remove a [background session](/docs/en/agent-view#manage-sessions-from-the-shell) from the list. When the removal is [refused over the session's worktree](/docs/en/agent-view#what-deleting-a-session-removes) and a seco…see the edit
--force-remove-worktree
CLI reference modified, high confidence
| `claude rm <id>` | Remove a [background session](/docs/en/agent-view#manage-sessions-from-the-shell) from the list. When the removal is [refused over the session's worktree](/docs/en/agent-view#what-deleting-a-session-removes) and a seco…see the edit
--discard-unpushed
CLI reference modified, high confidence
| `claude rm <id>` | Remove a [background session](/docs/en/agent-view#manage-sessions-from-the-shell) from the list. When the removal is [refused over the session's worktree](/docs/en/agent-view#what-deleting-a-session-removes) and a seco…see the edit
The entry above is what we published on the day. These lines were added later, as Anthropic's own pages caught up, and they sit beside the original rather than replacing it.
Added since
A small documentation edit on Manage sessions touched a line naming claude rm after this was published.
Transcripts age out under the [retention sweep rules](/docs/en/claude-directory#cleaned-up-automatically). To delete a project's transcripts and related state sooner, run [`claude purge`](/docs/en/claude-directory#clear-local-data). If you…sessions see the edit
Confirmed since
Anthropic's documentation has since written up claude rm, on Error reference.
push them and run 'claude rm 7c5dcf5d' again, or discard the worktree and its commits: claude rm 7c5dcf5d --discard-unpushed a1b2c3d000000000000000000000000000000000@0123456789abcdef0123456789abcdeferrors see the edit
One source agreesOne thing we can check says the same as this entry.
Anthropic's documentation agrees
claude rm on CLI reference