vibe clean

The clean command removes the current worktree and returns you to the main repository.

Usage

vibe clean

Options

--force, -f

Skip confirmation prompt when uncommitted changes exist.

vibe clean --force

--delete-branch

Delete the branch after removing the worktree.

vibe clean --delete-branch

--keep-branch

Keep the branch after removing the worktree. This overrides the delete_branch config setting.

vibe clean --keep-branch

-V, --verbose

Show detailed output including git commands being executed.

vibe clean --verbose

-q, --quiet

Suppress non-essential output.

vibe clean --quiet

--claude-code-worktree-hook v0.23.0+

Claude Code WorktreeRemove hook mode. Reads worktree path from stdin and removes the worktree.

vibe clean --claude-code-worktree-hook --force

See Claude Code Integration for setup details.

Configuration

Configure default behavior in .vibe.toml:

[clean]
delete_branch = true  # Delete branch by default when cleaning

Option	Default	Description
delete_branch	false	Delete branch after worktree removal

Fast Remove (Performance Optimization)

By default, vibe uses a fast removal strategy that moves the worktree directory to a temporary location and deletes it asynchronously in the background. This makes vibe clean feel instant even for large repositories.

Configure this in ~/.config/vibe/settings.json:

{
  "version": 3,
  "clean": {
    "fast_remove": true
  }
}

Option	Default	Description
fast_remove	true	Use fast async deletion (move + background delete)

How it works:

The behavior differs by platform:

• macOS: Items are moved to the system Trash via Finder. This allows recovery if needed and ensures reliable cleanup managed by the OS.
• Linux: Items are moved to XDG Trash. This allows recovery from your desktop file manager when available.
• Windows: Items are moved to the Recycle Bin. This allows recovery if needed and keeps cleanup consistent with the OS.

If system trash is unavailable or fails, vibe falls back to moving the worktree into the system temp directory (/tmp or %TEMP%) and deleting it in the background. Temp directories are automatically cleaned on system reboot.

Detailed process:

1. The worktree directory is instantly moved (O(1) rename operation)
2. Git worktree metadata is cleaned up on the now-empty directory
3. The actual file deletion happens asynchronously in the background
4. Previous .vibe-trash-* directories are automatically cleaned up

Note: If the fast move fails for any reason (e.g., cross-device link error), it automatically falls back to traditional deletion.

Behavior

Safety Checks

Before removing a worktree, vibe clean:

1. Checks for uncommitted changes
2. Prompts for confirmation if changes exist
3. Runs pre-clean hooks
4. Removes the worktree
5. Runs post-clean hooks
6. Changes directory to the main repository

Uncommitted Changes Warning

$ vibe clean
You have uncommitted changes. Are you sure you want to clean? (y/N)

If you have uncommitted changes, vibe will:

• Show a warning
• Ask for confirmation
• Only proceed if you explicitly confirm

Hooks

The clean command supports hooks for cleanup tasks:

[hooks]
pre_clean = ["git stash"]
post_clean = ["echo 'Cleanup complete'"]

Hook	When	Working Directory
pre_clean	Before worktree removal	Current worktree
post_clean	After worktree removal	Main repository

Pre-clean Hook Example

Save your work before cleaning:

[hooks]
pre_clean = [
  "git stash --include-untracked",
  "echo 'Changes stashed'"
]

Post-clean Hook Example

Clean up shared resources:

[hooks]
post_clean = [
  "docker-compose down",
  "echo 'Cleanup complete'"
]

Workflow

worktree (current)
     │
     ├── pre_clean hooks run
     │
     ├── git worktree remove
     │
     ├── post_clean hooks run
     │
     └── cd to main repository
            │
            ▼
main repository (new current)

Related

• start - Create worktrees
• Hooks - Configure cleanup hooks