LazyWorktree is a terminal user interface for managing Git worktrees. It provides a structured, keyboard-driven workflow for creating, inspecting, and navigating multiple worktrees within a single repository.

Built with BubbleTea, it focuses on fast iteration, clear state visibility, and tight integration with common Git tooling.

See other Screenshots below

• Worktree lifecycle: Create, rename, remove, absorb, and prune merged worktrees.
• Worktree state: Show dirty files, ahead/behind counts, and divergence from main.
• From current branch: Create from the current branch, optionally carrying over uncommitted changes.
• From issue: Create from a GitHub/GitLab issue with automatic branch naming.
• From PR or MR: Create from an open GitHub/GitLab pull or merge request.
• Forge integration: Show linked PR/MR, CI status, and checks via gh or glab.
• Cherry-picking: Apply commits from one worktree to another.
• Commit inspection: Browse commit logs with author initials and per-commit file trees.
• Status management: Stage, unstage, commit, edit, and diff files interactively.
• Diff viewing: View diffs in a pager, with optional delta integration.
• Terminal multiplexers: Manage per-worktree tmux or zellij sessions.
• Shell integration: Jump into selected worktrees and return to the last-used one.
• Command palette: Access actions, commands, and sessions with MRU-based navigation.
• Custom commands: Define keybindings, tmux/zellij layouts, and per-repo command workflows.
• Automation and hooks: Run init/terminate commands via .wt files with TOFU security.
• Automatic branch naming: Generate branch names from diffs, issues, or PRs via scripts.
• LazyGit integration: Launch lazygit for the selected worktree.

1. Install lazyworktree using your preferred method below.
2. Run lazyworktree inside a Git repository.
3. Press ? for help and key hints.

Common overrides:

lazyworktree --worktree-dir ~/worktrees

# Override config values via command line
lazyworktree --config lw.theme=nord --config lw.auto_fetch_prs=true

• Git: 2.31+ (recommended)
• Forge CLI: GitHub CLI (gh) or GitLab CLI (glab) for repo resolution and PR/MR status

Optional:

• delta: For syntax-highlighted diffs (highly recommended)
• lazygit: For full TUI git control
• tmux: For tmux integration support
• zellij: For zellij integration support

Build-time only:

• Go 1.25 or newer

Pre-built binaries for various platforms are provided in the Releases section.

brew tap chmouel/lazyworktree https://github.com/chmouel/lazyworktree
brew install lazyworktree --cask

yay -S lazyworktree-bin

Clone the repository and build:

git clone https://github.com/chmouel/lazyworktree.git
cd lazyworktree
go build -o lazyworktree ./cmd/lazyworktree

Install to your PATH:

go install ./cmd/lazyworktree

Or build and run directly:

go run ./cmd/lazyworktree/main.go

LazyWorktree provides shell helpers to change the current directory to the selected worktree on exit. These helpers are optional but recommended for interactive use.

Zsh helpers are provided under shell/functions.shell and can be sourced directly or downloaded.

See ./shell/README.md for more detailed instructions.

LazyWorktree supports command-line operations for creating and deleting worktrees without launching the TUI:

Create from a branch:

lazyworktree wt-create --from-branch feature/new-feature [--with-change] [--silent]

Create from a PR:

lazyworktree wt-create --from-pr 123 [--silent]

lazyworktree wt-delete [--no-branch] [--silent]

Deletes the worktree and associated branch (only if worktree name matches branch name). Use --no-branch to skip branch deletion.

Log Pane (when focused on commit log):

Commit File Tree (when viewing files in a commit):

Status Pane (when focused on status):

The status pane displays changed files in a collapsible tree view, grouped by directory (similar to lazygit). Directories can be expanded/collapsed, files are sorted alphabetically within each directory level.

Filter Mode:

Filter mode applies to the focused pane (worktrees, file names, commit titles).

• alt+n, alt+p: Navigate and update filter input with selected item
• ↑, ↓, ctrl+j, ctrl+k: Navigate list without changing filter input
• Enter: Exit filter mode (filter remains active)
• Esc, Ctrl+C: Exit filter mode

When a filter is active, the pane title shows a filter indicator with [Esc] Clear hint. Press Esc to clear the filter.

Search Mode:

• Type to jump to the first matching item
• n, N: Next / previous match
• Enter: Close search
• Esc, Ctrl+C: Clear search

Command History (! command):

Commands run via ! are saved per repository (100 entries max). Use ↑/↓ to navigate history.

Command Palette Actions:

• Select theme: Change the application theme with live preview (see Themes).
• Create from current branch: Copy your current branch to a new worktree. If uncommitted changes exist, tick "Include current file changes" to stash and reapply them in the new worktree. Any configured branch_name_script receives the diff for automatic naming.

• Click: Select and focus panes or items
• Scroll Wheel: Scroll through lists and content
  • Worktree table (left pane)
  • Status pane (right top pane)
  • Log table (right bottom pane)

Worktrees are expected to be organised under ~/.local/share/worktrees/<organization>-<repo_name> by default unless overridden via configuration.

lazyworktree reads ~/.config/lazyworktree/config.yaml (or .yml) for default settings. An example configuration is provided below (also available in config.example.yaml):

worktree_dir: ~/.local/share/worktrees
sort_mode: switched  # Options: "path", "active" (commit date), "switched" (last accessed)
auto_fetch_prs: false
auto_refresh: true
refresh_interval: 10  # Seconds
show_icons: true
search_auto_select: false
fuzzy_finder_input: false
palette_mru: true         # Enable MRU (Most Recently Used) sorting for command palette
palette_mru_limit: 5      # Number of recent commands to show (default: 5)
max_untracked_diffs: 10
max_diff_chars: 200000
max_name_length: 95       # Maximum length for worktree names in table display (0 disables truncation)
theme: ""       # Leave empty to auto-detect based on terminal background colour
                # (defaults to "dracula" for dark, "dracula-light" for light).
                # Options: see the Themes section below.
git_pager: delta
pager: "less --use-color --wordwrap -qcR -P 'Press q to exit..'"
editor: nvim
git_pager_args:
  - --syntax-theme
  - Dracula
trust_mode: "tofu" # Options: "tofu" (default), "never", "always"
merge_method: "rebase" # Options: "rebase" (default), "merge"
session_prefix: "wt-" # Prefix for tmux/zellij session names (default: "wt-")
# Branch name generation for issues and PRs
issue_branch_name_template: "issue-{number}-{title}" # Placeholders: {number}, {title}, {generated}
pr_branch_name_template: "pr-{number}-{title}" # Placeholders: {number}, {title}, {generated}
# Automatic branch name generation (see "Automatically Generated Branch Names")
branch_name_script: "" # Script to generate names from diff/issue/PR content
init_commands:
  - link_topsymlinks
terminate_commands:
  - echo "Cleaning up $WORKTREE_NAME"
custom_commands:
  t:
    command: make test
    description: Run tests
    show_help: true
    wait: true
# Custom worktree creation menu items
custom_create_menus:
  - label: "From JIRA ticket"
    description: "Create from JIRA issue"
    command: "jayrah browse 'SRVKP' --choose"
    interactive: true  # TUI-based commands need this to suspend lazyworktree
    post_command: "git commit --allow-empty -m 'Initial commit for ${WORKTREE_BRANCH}'"
    post_interactive: false  # Run post-command in background
  - label: "From clipboard"
    description: "Use clipboard as branch name"
    command: "pbpaste"

lazyworktree reads configuration from multiple sources with the following precedence (highest to lowest):

1. CLI overrides (using --config flag): Highest priority
2. Git local configuration (repository-specific via git config --local)
3. Git global configuration (user-wide via git config --global)
4. YAML configuration file (~/.config/lazyworktree/config.yaml)
5. Built-in defaults: Lowest priority

This allows flexible configuration at different levels. For example, you can set a default theme globally in your Git config, override it for a specific repository, and temporarily change it via the command line.

Settings can be stored in Git's configuration system with the lw. prefix. Examples:

# Set globally
git config --global lw.theme nord
git config --global lw.auto_fetch_prs true
git config --global lw.worktree_dir ~/.local/share/worktrees

# Set per-repository
git config --local lw.theme dracula
git config --local lw.init_commands "link_topsymlinks"
git config --local lw.init_commands "npm install"  # Multi-values supported

To view configured values:

git config --global --get-regexp "^lw\."
git config --local --get-regexp "^lw\."

Themes

• theme selects the colour theme. See Themes. Default: auto-detected (dracula for dark, dracula-light for light).
• Execute lazyworktree --show-syntax-themes to display the default delta --syntax-theme values for each UI theme.
• Use lazyworktree --theme <name> to select a UI theme directly.

Worktree list and refresh

• sort_mode: "switched" (last accessed, default), "active" (commit date), or "path" (alphabetical).
• auto_fetch_prs: fetch PR data on startup.
• auto_refresh: background refresh of git metadata (default: true).
• refresh_interval: refresh frequency in seconds (default: 10).
• show_icons: display icons (default: true).
• max_untracked_diffs, max_diff_chars: limits for diff display (0 disables).
• max_name_length: maximum display length for worktree names (default: 95, 0 disables truncation).

Search and palette

• search_auto_select: start with filter focused (or use --search-auto-select).
• fuzzy_finder_input: show fuzzy suggestions in input dialogs.
• palette_mru: enable MRU sorting in command palette (default: true). Control count with palette_mru_limit (default: 5).

Diff, pager, and editor

• git_pager: diff formatter (default: delta). Empty string disables formatting.
• git_pager_args: arguments for git_pager. Auto-selects syntax theme for delta.
• git_pager_interactive: set true for interactive viewers like diffnav or tig.
• pager: pager for output display (default: $PAGER, fallback to less).
• editor: editor for Status pane e key (default: $EDITOR, fallback to nvim).

Worktree lifecycle

• init_commands and terminate_commands execute prior to any repository-specific .wt commands (if present).

Sync and multiplexers

• merge_method: "rebase" (default) or "merge". Controls Absorb and Sync (S) behaviour.
• session_prefix: prefix for tmux/zellij sessions (default: wt-). Palette filters by this prefix.

Branch naming

• branch_name_script: script for automatic branch suggestions. See Automatically generated branch names.
• issue_branch_name_template, pr_branch_name_template: templates with placeholders {number}, {title}, {generated}.

Custom create menu

• custom_create_menus: add custom items to the creation menu (c key). Supports interactive and post_command.

lazyworktree includes built-in themes:

To select a theme, configure it in your configuration file:

theme: dracula  # or any listed above

You can define custom themes in your configuration file that inherit from built-in themes or define completely new colour schemes.

Inheriting from a built-in theme:

custom_themes:
  my-dark:
    base: dracula
    accent: "#FF6B9D"
    text_fg: "#E8E8E8"

  my-light:
    base: dracula-light
    background: "#FAFAFA"
    accent: "#0066CC"

Defining a complete theme (all 14 colour fields required):

custom_themes:
  completely-custom:
    background: "#1A1A1A"
    accent: "#00FF00"
    accent_fg: "#000000"
    accent_dim: "#2A2A2A"
    border: "#3A3A3A"
    border_dim: "#2A2A2A"
    muted_fg: "#888888"
    text_fg: "#FFFFFF"
    success_fg: "#00FF00"
    warn_fg: "#FFFF00"
    error_fg: "#FF0000"
    cyan: "#00FFFF"
    pink: "#FF00FF"
    yellow: "#FFFF00"

Custom themes can inherit from other custom themes:

custom_themes:
  base-custom:
    base: dracula
    accent: "#FF0000"
  derived:
    base: base-custom
    accent: "#00FF00"

Available colour fields:

• background - Main background colour
• accent - Primary accent colour (highlights, selected items)
• accent_fg - Foreground colour for text on accent background
• accent_dim - Dimmed accent colour (selected rows/panels)
• border - Border colour
• border_dim - Dimmed border colour
• muted_fg - Muted text colour
• text_fg - Primary text colour
• success_fg - Success indicator colour
• warn_fg - Warning indicator colour
• error_fg - Error indicator colour
• cyan - Cyan accent colour
• pink - Pink accent colour
• yellow - Yellow accent colour

Colour values must be in hex format (#RRGGBB or #RGB). When using a base theme, only specify colours you want to override. When not using a base, all 14 colour fields are required.

Custom themes appear in the theme selection screen alongside built-in themes.

When viewing a worktree with an associated PR/MR, lazyworktree automatically retrieves and displays CI check statuses in the information pane.

• ✓ Green - Passed
• ✗ Red - Failed
• ● Yellow - Pending/Running
• ○ Grey - Skipped
• ⊘ Grey - Cancelled

CI status is retrieved lazily (only for the selected worktree) and cached for 30 seconds to maintain UI responsiveness. Press p to force a refresh of CI status.

Define custom keybindings in ~/.config/lazyworktree/config.yaml. Commands run interactively (TUI suspends) and appear in the command palette. Use show_output to pipe output through the pager.

Defaults: t opens tmux, Z opens zellij. Override by defining custom_commands.t or custom_commands.Z. The palette lists active sessions matching session_prefix (default: wt-).

Add a custom_commands section to your config:

custom_commands:
  e:
    command: nvim
    description: Editor
    show_help: true
  s:
    command: zsh
    description: Shell
    show_help: true
  T: # Run tests and wait for keypress
    command: make test
    description: Run tests
    show_help: false
    wait: true
  o: # Show output in the pager
    command: git status -sb
    description: Status
    show_help: true
    show_output: true
  a: # Open CLaude CLI in the selected workspace in a new kitty tab
    command: "kitten @ launch --type tab --cwd $WORKTREE_PATH -- claude"
    description: Open Claude
    show_help: true
  t: # Open a tmux session with multiple windows
    description: Tmux
    show_help: true
    tmux: # If you specify zellij instead of tmux this would manage zellij sessions
      session_name: "wt:$WORKTREE_NAME"
      attach: true
      on_exists: switch
      windows:
        - name: claude
          command: claude
        - name: shell
          command: zsh
        - name: lazygit
          command: lazygit

If windows is omitted or empty, lazyworktree creates a single shell window.

If windows is omitted or empty, lazyworktree creates a single shell tab. Zellij session names cannot include /, \, or :, so lazyworktree replaces them with -.

Custom commands have access to the same environment variables as init/terminate commands:

• WORKTREE_BRANCH: Name of the git branch
• MAIN_WORKTREE_PATH: Path to the main repository
• WORKTREE_PATH: Path to the selected worktree
• WORKTREE_NAME: Name of the worktree (directory name)
• REPO_NAME: Name of the repository (from GitHub/GitLab)

Custom commands support the same key formats as built-in keybindings:

• Single keys: e, s, t, l, etc.
• Modifier combinations: ctrl+e, ctrl+t, alt+s, etc.
• Special keys: enter, esc, tab, space, etc.

Examples:

custom_commands:
  "ctrl+e":
    command: nvim
    description: Open editor with Ctrl+E
  "alt+t":
    command: make test
    description: Run tests with Alt+T
    wait: true

Custom commands take precedence over built-in keys. If you define a custom command with key s, it overrides the built-in sort toggle.

Create a .wt file in your main repository to define commands that run when creating or removing a worktree. Format inspired by wt.

init_commands:
    - link_topsymlinks
    - cp $MAIN_WORKTREE_PATH/.env $WORKTREE_PATH/.env
    - npm install
    - code .

terminate_commands:
    - echo "Cleaning up $WORKTREE_NAME"

The following environment variables are available to your commands:

• WORKTREE_BRANCH: Name of the git branch.
• MAIN_WORKTREE_PATH: Path to the main repository.
• WORKTREE_PATH: Path to the new worktree being created or removed.
• WORKTREE_NAME: Name of the worktree (directory name).

Since .wt files can execute arbitrary commands, lazyworktree uses a Trust on First Use security model.

• First Run: When encountering a new or modified .wt file, lazyworktree pauses and displays the commands. Select Trust (run and save), Block (skip), or Cancel.
• Trusted: Once trusted, commands run silently in the background until the .wt file changes again.
• Persistence: Trusted file hashes are stored in ~/.local/share/lazyworktree/trusted.json.

Configure via trust_mode in config.yaml:

• tofu (Default): Prompts for confirmation on new or changed files. Secure and usable.
• never: Never runs commands from .wt files. Safest for untrusted environments.
• always: Always runs commands without prompting. Useful for personal/internal environments but risky.

• link_topsymlinks: A built-in automation command (not a shell command) that executes without TOFU prompts once the .wt file is trusted. It performs the following:
  • Symlinks all untracked and ignored files from the root of the main worktree to the new worktree (excluding subdirectories).
  • Symlinks common editor configurations (.vscode, .idea, .cursor, .claude).
  • Ensures a tmp/ directory exists in the new worktree.
  • Automatically runs direnv allow if a .envrc file is present.

Special characters are converted to hyphens for Git compatibility. Leading/trailing hyphens are removed, consecutive hyphens collapsed. Length capped at 50 (manual) or 100 (auto) characters.

Configure branch_name_script to generate branch names via a helper tool, for example aichat or claude code.

• PRs/issues: Script outputs a title available via {generated} placeholder.
• Diffs: Script outputs a complete branch name.

Add branch_name_script to your ~/.config/lazyworktree/config.yaml:

# For PRs/issues: generate a title (available via {generated} placeholder)
branch_name_script: "aichat -m gemini:gemini-2.5-flash-lite 'Generate a short title for this PR or issue. Output only the title (like feat-ai-session-manager), nothing else.'"

# Choose which template to use:
pr_branch_name_template: "pr-{number}-{generated}"  # Use generated title
# pr_branch_name_template: "pr-{number}-{title}"    # Use original PR title
# pr_branch_name_template: "pr-{number}-{generated}-{title}"  # Use both!

# For diffs: generate a complete branch name
# branch_name_script: "aichat -m gemini:gemini-2.5-flash-lite 'Generate a short git branch name (no spaces, use hyphens) for this diff. Output only the branch name, nothing else.'"

When creating worktrees from PRs or issues, the following placeholders are available:

• {number} - The PR/issue number
• {title} - The original sanitised PR/issue title (always available)
• {generated} - The generated title (falls back to {title} if the script is not configured or returns empty output)
• {pr_author} - The PR author's username (PRs only, sanitised)

Examples:

If the script fails or returns empty output, {generated} automatically falls back to the sanitised original title.

The script receives content on stdin (diff, issue, or PR title+body) and outputs the branch name on stdout (first line used). Timeout: 30 seconds. Falls back to the original title if the script fails.

Available to scripts: LAZYWORKTREE_TYPE (pr/issue/diff), LAZYWORKTREE_NUMBER, LAZYWORKTREE_TEMPLATE, LAZYWORKTREE_SUGGESTED_NAME.

Example:

# Different prompts for different types
branch_name_script: |
  if [ "$LAZYWORKTREE_TYPE" = "diff" ]; then
    aichat -m gemini:gemini-2.5-flash-lite 'Generate a complete branch name for this diff'
  else
    aichat -m gemini:gemini-2.5-flash-lite 'Generate a short title (no pr- prefix) for this PR/issue'
  fi

# Use PR/issue number in the prompt
branch_name_script: |
  aichat -m gemini:gemini-2.5-flash-lite "Generate a title for PR #$LAZYWORKTREE_NUMBER. Output only the title."

lazyworktree covers a broader set of use cases than most Git worktree tools, especially for interactive and human-driven workflows.

For a fair and detailed comparison with other popular worktree managers (including their respective strengths and trade-offs), see the COMPARAISON document.

Previously, this was a Python textual application; however, the startup time proved excessive, prompting a migration to a Go-based charmbracelet bubble Terminal User Interface. The original Python implementation remains available for review or testing at https://github.com/chmouel/lazyworktree/tree/python

Apache-2.0

• 🐘 Fediverse - <@chmouel@chmouel.com>
• 🐦 Twitter - <@chmouel>
• 📝 Blog - <https://blog.chmouel.com>