Getting Started

What is vibe?

vibe is a CLI tool that simplifies Git Worktree management. It helps you:

• Create worktrees for new features without leaving your main repository
• Automatically copy configuration files and dependencies
• Run setup hooks when creating or cleaning up worktrees
• Safely manage worktree lifecycle with interactive prompts

Quick Start

1. Install vibe

Homebrew

brew install kexi/tap/vibe

npm/npx

# Global install
npm install -g @kexi/vibe

# Or run directly with npx
npx @kexi/vibe start feat/my-feature

Note

Shell setup (Step 2) is required. Select the “npx” option for npx usage.

Tip

Global install is recommended for frequent use. npx has slower startup due to package resolution overhead.

Bun

# Global install
bun add -g @kexi/vibe

# Or run directly with bunx
bunx @kexi/vibe start feat/my-feature

Note

Shell setup (Step 2) is required. Select the “bunx” option for bunx usage.

Tip

Global install is recommended for frequent use. bunx has slower startup due to package resolution overhead.

Linux

# Ubuntu/Debian (x64)
curl -LO https://github.com/kexi/vibe/releases/latest/download/vibe_amd64.deb
sudo apt install ./vibe_amd64.deb

# Other distributions (x64)
curl -L https://github.com/kexi/vibe/releases/latest/download/vibe-linux-x64 -o vibe
chmod +x vibe && sudo mv vibe /usr/local/bin/

Windows

Invoke-WebRequest -Uri "https://github.com/kexi/vibe/releases/latest/download/vibe-windows-x64.exe" -OutFile "$env:LOCALAPPDATA\vibe.exe"
# Add to PATH (first time only)
$path = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$path;$env:LOCALAPPDATA", "User")

2. Set up your shell

Add one of the following to your shell configuration (choose based on your installation method):

Zsh

# Add to ~/.zshrc (choose one)

# For global install (Homebrew, npm -g, bun -g)
vibe() { eval "$(command vibe "$@")" }

# For npx (without global install)
vibe() { eval "$(npx @kexi/vibe "$@")" }
# Or for bunx:
# vibe() { eval "$(bunx @kexi/vibe "$@")" }

Bash

# Add to ~/.bashrc (choose one)

# For global install (Homebrew, npm -g, bun -g)
vibe() { eval "$(command vibe "$@")"; }

# For npx (without global install)
vibe() { eval "$(npx @kexi/vibe "$@")"; }
# Or for bunx:
# vibe() { eval "$(bunx @kexi/vibe "$@")"; }

Fish

# Add to ~/.config/fish/config.fish (choose one)

# For global install (Homebrew, npm -g, bun -g)
function vibe
    eval (command vibe $argv)
end

# For npx (without global install)
function vibe
    eval (npx @kexi/vibe $argv)
end
# Or for bunx:
# function vibe
#     eval (bunx @kexi/vibe $argv)
# end

Nushell

# Add to ~/.config/nushell/config.nu (choose one)

# For global install (Homebrew, npm -g, bun -g)
def --env vibe [...args] {
    ^vibe ...$args | lines | each { |line| nu -c $line }
}

# For npx (without global install)
def --env vibe [...args] {
    npx @kexi/vibe ...$args | lines | each { |line| nu -c $line }
}
# Or for bunx:
# def --env vibe [...args] {
#     bunx @kexi/vibe ...$args | lines | each { |line| nu -c $line }
# }

PowerShell

# Add to your $PROFILE (choose one)

# For global install (Homebrew, npm -g, bun -g)
function vibe { Invoke-Expression (& vibe.exe $args) }

# For npx (without global install)
function vibe { Invoke-Expression (& npx @kexi/vibe $args) }
# Or for bunx:
# function vibe { Invoke-Expression (& bunx @kexi/vibe $args) }

3. Create your first worktree

# Start working on a new feature
vibe start feat/my-new-feature

# Your terminal is now in the new worktree!
# Make your changes, commit, push, etc.

# When done, clean up the worktree
vibe clean

Basic Workflow

main repository
     │
     ├── vibe start feat/feature-a  →  repo-feat-feature-a/
     │                                      │
     │                                      └── (work on feature)
     │
     └── vibe clean  ←─────────────────────────┘
           (returns to main, removes worktree)

Next Steps

• Installation - Detailed installation instructions
• Shell Setup - Configure your shell
• Configuration - Set up .vibe.toml