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/Windows: Items are moved to the system temp directory (/tmp or %TEMP%) and deleted in the background using nohup. Temp directories are automatically cleaned on system reboot.

Detailed process:

The worktree directory is instantly moved (O(1) rename operation)
Git worktree metadata is cleaned up on the now-empty directory
The actual file deletion happens asynchronously in the background
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:

Checks for uncommitted changes
Prompts for confirmation if changes exist
Runs pre-clean hooks
Removes the worktree
Runs post-clean hooks
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)

start - Create worktrees
Hooks - Configure cleanup hooks