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

npm install -g @kexi/vibe

Windows x64 is supported through the @kexi/vibe-win32-x64 binary package. WSL2 users can also use the Linux instructions above.

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 --wrapped vibe [...args] {
    let out = (^vibe --eval-dialect nu ...$args)
    for line in ($out | lines) {
        if ($line | str starts-with "__VIBE_CD__") {
            cd ($line | str replace "__VIBE_CD__" "")
        } else {
            print $line
        }
    }
}

# For npx (without global install)
def --env --wrapped vibe [...args] {
    let out = (npx @kexi/vibe --eval-dialect nu ...$args)
    for line in ($out | lines) {
        if ($line | str starts-with "__VIBE_CD__") {
            cd ($line | str replace "__VIBE_CD__" "")
        } else {
            print $line
        }
    }
}
# Or for bunx:
# def --env --wrapped vibe [...args] {
#     let out = (bunx @kexi/vibe --eval-dialect nu ...$args)
#     for line in ($out | lines) {
#         if ($line | str starts-with "__VIBE_CD__") {
#             cd ($line | str replace "__VIBE_CD__" "")
#         } else {
#             print $line
#         }
#     }
# }

Note

Requires vibe 2.2.0 or later and nushell 0.83 or later. Replace any older nu -c snippet you pasted before — it never actually changed your directory and rejected any command carrying a flag. Keep both --wrapped (so flags reach ...args) and for (nushell discards environment changes made inside an each closure).

PowerShell

# Add to your $PROFILE (choose one)

# For global install (Homebrew, npm -g, bun -g)
function vibe { $out = & vibe.exe --eval-dialect powershell @args; if ($out) { Invoke-Expression ($out -join "`n") } }

# For npx (without global install)
function vibe { $out = & npx @kexi/vibe --eval-dialect powershell @args; if ($out) { Invoke-Expression ($out -join "`n") } }
# Or for bunx:
# function vibe { $out = & bunx @kexi/vibe --eval-dialect powershell @args; if ($out) { Invoke-Expression ($out -join "`n") } }

Note

Requires vibe 2.2.0 or later. Replace any older Invoke-Expression (& vibe.exe $args) snippet you pasted before — it mishandled paths containing a single quote and threw an error when vibe produced no output.

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