### Global Configuration Example (YAML)

Source: https://chmouel.github.io/lazyworktree/docs/configuration

An example of the global configuration file (`~/.config/lazyworktree/config.yaml`). It demonstrates settings for worktree directory, sorting, layout, refresh intervals, and more.

```yaml
worktree_dir: ~/.local/share/worktrees
sort_mode: switched  # Options: "path", "active" (commit date), "switched" (last accessed)
layout: default      # Pane arrangement: "default" or "top"
auto_refresh: true
refresh_interval: 10  # Seconds
disable_pr: false     # Disable all PR/MR fetching and display (default: false)
icon_set: nerd-font-v3
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 "rose-pine" 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}, {pr_author}
# Automatic branch name generation (see "Automatically Generated Branch Names")
branch_name_script: "" # Script to generate names from diff/issue/PR content
# Automatic worktree note generation when creating from PR/MR or issue
worktree_note_script: "" # Script to generate notes from PR/issue title+body
# Optional shared note storage file (single JSON for all repositories)
worktree_notes_path: "" # e.g. ~/.local/share/lazyworktree/worktree-notes.json
# Note storage type: "onejson" (default) or "splitted" (individual markdown files)
# When "splitted", worktree_notes_path is a template with $REPO_OWNER, $REPO_REPONAME, $WORKTREE_NAME
# e.g. worktree_notes_path: ~/notes/$REPO_OWNER/$REPO_REPONAME/$WORKTREE_NAME/note.md
worktree_note_type: "" # "onejson" or "splitted"
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"

```

--------------------------------

### Fish: Setup with Completion and 'jt' Function

Source: https://chmouel.github.io/lazyworktree/docs/shell-integration

Configure Fish with helper functions, a 'jt' function, and shell completion for the 'jt' command.

```fish
source /path/to/lazyworktree/shell/functions.fish

function jt
    worktree_jump $(git rev-parse --show-toplevel) $argv
end

complete -c jt -f -a '(_worktree_jump $(git rev-parse --show-toplevel))'
```

--------------------------------

### Bash: Setup with Completion and 'jt' Alias

Source: https://chmouel.github.io/lazyworktree/docs/shell-integration

Configure Bash with helper functions, a 'jt' alias, and shell completion for the 'jt' command.

```bash
source /path/to/lazyworktree/shell/functions.bash

jt() { worktree_jump $(git rev-parse --show-toplevel) "$@"; }
_jt() { _worktree_jump $(git rev-parse --show-toplevel); }
complete -o nospace -F _jt jt
```

--------------------------------

### Zsh: Setup with Completion and 'jt' Alias

Source: https://chmouel.github.io/lazyworktree/docs/shell-integration

Configure Zsh with helper functions, a 'jt' alias, and shell completion for the 'jt' command.

```zsh
source /path/to/lazyworktree/shell/functions.zsh

jt() { worktree_jump $(git rev-parse --show-toplevel) "$@"; }
_jt() { _worktree_jump $(git rev-parse --show-toplevel); }
compdef _jt jt
```

--------------------------------

### Install lazyworktree directly with Go

Source: https://chmouel.github.io/lazyworktree/docs/installation

Install the latest version of lazyworktree directly using `go install`. Ensure your Go environment is set up correctly and GOPATH is configured.

```bash
go install github.com/chmouel/lazyworktree/cmd/lazyworktree@latest
```

--------------------------------

### Example .wt Lifecycle Hooks

Source: https://chmouel.github.io/lazyworktree/docs/configuration/lifecycle-hooks

Define commands to run during worktree initialization and termination. Use environment variables like WORKTREE_PATH for dynamic path resolution.

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

terminate_commands:
  - echo "Cleaning up $WORKTREE_NAME"
```

--------------------------------

### Install aichat CLI

Source: https://chmouel.github.io/lazyworktree/docs/guides/ai-integration

Install the aichat command-line interface using Homebrew on macOS or Cargo on Linux.

```bash
# macOS
brew install aichat
```

```bash
# Linux
cargo install aichat
```

--------------------------------

### Keybindings Configuration Example

Source: https://chmouel.github.io/lazyworktree/docs/action-ids

Configure universal and pane-specific keybindings to map keys to built-in palette actions. Pane-specific bindings override universal ones for the same key.

```yaml
keybindings:
  universal:
    G: git-lazygit
    ctrl+d: worktree-delete
    F: git-fetch
  worktrees:
    x: worktree-delete
  log:
    d: git-diff

```

--------------------------------

### Example Script Input and Output

Source: https://chmouel.github.io/lazyworktree/docs/worktree-notes

Demonstrates the input received by the worktree note script (PR title and description) and the expected output format for the generated worktree note.

```text
# The script receives on stdin:
# Add session management
#
# This PR implements session management with JWT tokens.
# Sessions expire after 30 minutes of inactivity.
# Includes refresh token rotation.

# The script outputs to stdout:
# ## Implementation Notes
# - JWT-based session tokens with 30-min inactivity timeout
# - Refresh token rotation on each use
# - Key files: auth/session.go, middleware/auth.go


```

--------------------------------

### Complete Custom Commands Configuration

Source: https://chmouel.github.io/lazyworktree/docs/custom-commands

An extensive example demonstrating various custom command configurations including simple commands, output display, tmux sessions, new tab execution, and wait behavior.

```yaml
custom_commands:
  universal:
    e:
      command: nvim
      description: Editor
      show_help: true
    s:
      command: zsh
      description: Shell
      show_help: true
    T:
      command: make test
      description: Run tests
      show_help: false
      wait: true
    o:
      command: git status -sb
      description: Status
      show_help: true
      show_output: true
    c:
      command: claude
      description: Claude Code
      new_tab: true
      show_help: true
    t:
      description: Tmux
      show_help: true
      tmux:
        session_name: "wt:$WORKTREE_NAME"
        attach: true
        on_exists: switch
        windows:
          - name: claude
            command: claude
          - name: shell
            command: zsh
          - name: lazygit
            command: lazygit

```

--------------------------------

### Build lazyworktree from source

Source: https://chmouel.github.io/lazyworktree/docs/installation

Clone the repository and build the binary locally. This method is useful for development or if you prefer building from source. Ensure you have Go installed.

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

--------------------------------

### Container with Tmux and Entrypoint

Source: https://chmouel.github.io/lazyworktree/docs/custom-commands

Configure a command to run inside a container, with tmux managing multiple windows. This example uses a Go image and specifies network settings.

```yaml
custom_commands:
  universal:
    ctrl+l:
      description: Dev container
      tmux:
        session_name: "dev:$WORKTREE_NAME"
        windows:
          - name: test
            command: "go test -v ./..."
          - name: shell
      container:
        image: "golang:1.22"
        extra_args:
          - "--network=host"

```

--------------------------------

### Container with Specific Entrypoint

Source: https://chmouel.github.io/lazyworktree/docs/custom-commands

Run a command in a container, specifying a custom entrypoint and interactive mode. This example uses a Python image and `/bin/sh` as the entrypoint.

```yaml
custom_commands:
  universal:
    ctrl+s:
      description: Shell in Python container
      container:
        image: "python:3.12"
        entrypoint: "/bin/sh"
        interactive: true

```

--------------------------------

### Install lazyworktree with Homebrew on macOS

Source: https://chmouel.github.io/lazyworktree/docs/installation

Use this command to tap the repository and install lazyworktree via Homebrew Cask. Ensure Homebrew is installed.

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

--------------------------------

### Example Markdown Checkbox Syntax

Source: https://chmouel.github.io/lazyworktree/docs/core/notes-and-taskboard

Use this syntax in worktree notes to create actionable tasks for the taskboard.

```markdown
- [ ] draft release notes
- [x] update changelog

```

--------------------------------

### Custom AI Script Example

Source: https://chmouel.github.io/lazyworktree/docs/guides/ai-integration

An example bash script that reads content from stdin, sends it to a custom AI API using curl, and extracts the result using jq.

```bash
#!/bin/bash
content=$(cat)
curl -s https://api.your-ai-service.com/generate \
  -d "{\"prompt\": \"Generate branch name\", \"content\": \"$content\"}" \
  | jq -r '.result'
```

--------------------------------

### Basic zellij Session Configuration

Source: https://chmouel.github.io/lazyworktree/docs/guides/multiplexer-integration

Configure a basic zellij session that attaches immediately and switches to an existing session if found. Suitable for simple zellij setups.

```yaml
custom_commands:
  Z:
    description: Zellij
    show_help: true
    zellij:
      session_name: "wt:$WORKTREE_NAME"
      attach: true
      on_exists: switch

```

--------------------------------

### Manual Worktree Note Example

Source: https://chmouel.github.io/lazyworktree/docs/worktree-notes

A brief and practical note for a worktree, capturing context and next actions. This format is useful for quickly understanding the worktree's purpose and status.

```markdown
## Context
- PR: #142
- Goal: finish retry handling in webhook reconciliation

## Next actions
- add failing test for timeout branch
- update retry backoff to cap at 30s


```

--------------------------------

### Describe the Full CLI

Source: https://chmouel.github.io/lazyworktree/docs/cli/describe

Use `lazyworktree describe` or `lazyworktree describe --all` to get the complete command structure of the CLI. This is useful for understanding all available commands and their options.

```bash
# Describe the full CLI (root + all subcommands)
lazyworktree describe
lazyworktree describe --all
```

--------------------------------

### Example Using Environment Variables in tmux Configuration

Source: https://chmouel.github.io/lazyworktree/docs/guides/multiplexer-integration

Demonstrates using environment variables like $REPO_NAME and $WORKTREE_NAME to dynamically configure tmux session names and window properties. This allows for more flexible and context-aware session management.

```yaml
custom_commands:
  t:
    description: Project session
    tmux:
      session_name: "$REPO_NAME:$WORKTREE_NAME"
      windows:
        - name: "$WORKTREE_BRANCH"
          command: nvim
          cwd: $WORKTREE_PATH
        - name: root
          command: zsh
          cwd: $MAIN_WORKTREE_PATH

```

--------------------------------

### Install lazyworktree with AUR on Arch Linux

Source: https://chmouel.github.io/lazyworktree/docs/installation

For Arch Linux users, install the lazyworktree package using the AUR helper `yay`. This command fetches and builds the package from the Arch User Repository.

```bash
yay -S lazyworktree-bin
```

--------------------------------

### Basic tmux Session Configuration

Source: https://chmouel.github.io/lazyworktree/docs/guides/multiplexer-integration

Configure a basic tmux session that attaches immediately and switches to an existing session if found. Use this for simple, single-window tmux setups.

```yaml
custom_commands:
  t:
    description: Tmux session
    show_help: true
    tmux:
      session_name: "wt:$WORKTREE_NAME"
      attach: true
      on_exists: switch

```

--------------------------------

### Set Global Git Configuration for Theme and Worktree Directory

Source: https://chmouel.github.io/lazyworktree/docs/configuration

Configure lazyworktree settings globally using `git config`. This example shows how to set the theme and the worktree directory.

```bash
git config --global lw.theme nord
```

```bash
git config --global lw.worktree-dir ~/.local/share/worktrees
```

--------------------------------

### Example Worktree Note Generation Script

Source: https://chmouel.github.io/lazyworktree/docs/worktree-notes

A bash script that reads PR content from stdin, uses `aichat` with a specific model to generate developer notes, and prints the output to stdout. It includes error handling for piped commands.

```bash
#!/usr/bin/env bash
set -euo pipefail

PR_CONTENT=$(cat)

printf '%s\n' "$PR_CONTENT" | aichat \
  -m gemini:gemini-2.5-flash-lite \
  'Create concise developer worktree notes with context, done items, and next actions.'


```

--------------------------------

### Branch Name Sanitization Example

Source: https://chmouel.github.io/lazyworktree/docs/core/worktree-operations

Illustrates how input strings are converted into valid branch names by replacing special characters with hyphens, removing leading/trailing hyphens, and collapsing consecutive hyphens.

```markdown
Input | Converted  
---|---
`feature.new` | `feature-new`
`bug fix here` | `bug-fix-here`
`feature:test` | `feature-test`
`user@domain/fix` | `user-domain-fix`
```

--------------------------------

### Conventional Commit Example: Fix

Source: https://chmouel.github.io/lazyworktree/docs/development/contributing

An example of a conventional commit for fixing a bug, following the title and body structure.

```git
fix: corrected branch name fallback on script timeout

The {generated} placeholder silently returned an empty string
when the AI script exceeded 30 seconds.

```

--------------------------------

### Conventional Commit Example: Feature

Source: https://chmouel.github.io/lazyworktree/docs/development/contributing

An example of a conventional commit for adding a new feature, adhering to the specified title and body format.

```git
feat: added worktree notes synchronisation

Allowed teams to share implementation context across machines
by storing notes in a committable JSON file.

```

--------------------------------

### Typical Documentation Workflow

Source: https://chmouel.github.io/lazyworktree/docs/development/contributing

Steps to follow for editing documentation, regenerating references, checking for errors, and previewing the site locally.

```bash
# Edit docs/ files
make docs-sync        # Regenerate references from source
make docs-check       # Verify everything is in order
make docs-serve       # Preview locally

```

--------------------------------

### Fish: Download Helper and Define 'jt' Function

Source: https://chmouel.github.io/lazyworktree/docs/shell-integration

Download the Fish helper functions and add them to your ~/.config/fish/config.fish, then define a 'jt' function for jumping to worktrees.

```fish
mkdir -p ~/.config/fish/conf.d
curl -sL https://raw.githubusercontent.com/chmouel/lazyworktree/refs/heads/main/shell/functions.fish -o ~/.config/fish/conf.d/lazyworktree.fish

# Add to ~/.config/fish/config.fish
function jt
    worktree_jump $(git rev-parse --show-toplevel) $argv
end
```

--------------------------------

### Jump to Worktree from Shell

Source: https://chmouel.github.io/lazyworktree/docs/getting-started

Use this command to change your current directory to the selected worktree path. Ensure lazyworktree is installed and executable in your PATH.

```shell
cd "$(lazyworktree)"

```

--------------------------------

### Define a Simple Command

Source: https://chmouel.github.io/lazyworktree/docs/custom-commands

Use this to bind a simple shell command to a key. `show_help: true` makes it visible in the help screen.

```yaml
custom_commands:
  universal:
    e:
      command: nvim
      description: Editor
      show_help: true

```

--------------------------------

### Create Worktree with Metadata

Source: https://chmouel.github.io/lazyworktree/docs/cli/create

Creates a worktree and associates it with a description, tags, and a note. Notes can be provided directly or from a file.

```bash
lazyworktree create my-feature --description "Implement login flow" --tags "auth,backend"
lazyworktree create my-feature --note "See RFC-42 for context"
lazyworktree create my-feature --note-file ./notes.md
```

--------------------------------

### Launch Container with Default Entrypoint

Source: https://chmouel.github.io/lazyworktree/docs/guides/container-execution

Specify only an image to launch a container with its default entrypoint. The worktree is automatically mounted at `/workspace`. Use `interactive: true` for a shell.

```yaml
custom_commands:
  ctrl+d:
    description: Default shell in container
    container:
      image: "ubuntu:24.04"
      interactive: true

```

--------------------------------

### Define .wt file for worktree lifecycle commands

Source: https://chmouel.github.io/lazyworktree/docs/worktree-lifecycle

Place this YAML file in your repository root to specify commands for worktree initialization and termination. Commands are executed sequentially, and failures do not halt the process. Available environment variables like WORKTREE_PATH and MAIN_WORKTREE_PATH can be used.

```yaml
init_commands:
    - link_topsymlinks
    - cp $MAIN_WORKTREE_PATH/.env $WORKTREE_PATH/.env
    - npm install
    - direnv allow $WORKTREE_PATH
    - docker compose -f $WORKTREE_PATH/docker-compose.yml up -d

terminate_commands:
    - docker compose -f $WORKTREE_PATH/docker-compose.yml down
    - echo "Cleaned up $WORKTREE_NAME"

```

--------------------------------

### Clone and Build LazyWorktree

Source: https://chmouel.github.io/lazyworktree/docs/development/contributing

Clone the repository and build the project binary. The executable will be placed in the bin/lazyworktree directory.

```bash
git clone https://github.com/chmouel/lazyworktree.git
cd lazyworktree
make build

```

--------------------------------

### Set Note from File

Source: https://chmouel.github.io/lazyworktree/docs/cli/note

Enables setting the note content by reading from a specified file. Use the `-i` flag followed by the filename.

```bash
lazyworktree note edit my-feature -i note.md
```

--------------------------------

### Fish: Source Local Helper and Define 'jt' Function

Source: https://chmouel.github.io/lazyworktree/docs/shell-integration

Add this to your ~/.config/fish/config.fish to source the local Fish helper functions and define a 'jt' function for jumping to worktrees.

```fish
# Add to ~/.config/fish/config.fish
source /path/to/lazyworktree/shell/functions.fish

function jt
    worktree_jump $(git rev-parse --show-toplevel) $argv
end
```

--------------------------------

### List Worktrees in Table Format

Source: https://chmouel.github.io/lazyworktree/docs/cli/list

Displays available worktrees in a human-readable table format. This is the default output when no options are specified.

```bash
lazyworktree list
```

--------------------------------

### Creating Worktrees

Source: https://chmouel.github.io/lazyworktree/docs/cli

Create new worktrees with options for naming, basing on branches or issues, interactive selection, and running commands post-creation. Use --no-workspace to create only a branch.

```bash
lazyworktree create                          # Auto-generated from current branch
```

```bash
lazyworktree create my-feature               # Explicit name
```

```bash
lazyworktree create my-feature --with-change # With uncommitted changes
```

```bash
lazyworktree create --from-branch main my-feature
```

```bash
lazyworktree create --from-pr 123
```

```bash
lazyworktree create --from-issue 42          # From issue (base: current branch)
```

```bash
lazyworktree create --from-issue 42 --from-branch main  # From issue with explicit base
```

```bash
lazyworktree create -I                       # Interactively select issue (fzf or list)
```

```bash
lazyworktree create -I --from-branch main    # Interactive issue with explicit base
```

```bash
lazyworktree create -P                       # Interactively select PR (fzf or list)
```

```bash
lazyworktree create -P --query "dark"             # Pre-filter interactive PR selection
```

```bash
lazyworktree create -I --query "login"       # Pre-filter interactive issue selection
```

```bash
lazyworktree create --from-pr 123 --no-workspace        # Branch only, no worktree
```

```bash
lazyworktree create --from-issue 42 --no-workspace      # Branch only, no worktree
```

```bash
lazyworktree create -I --no-workspace                    # Interactive issue, branch only
```

```bash
lazyworktree create -P --no-workspace                    # Interactive PR, branch only
```

```bash
lazyworktree create my-feature --exec 'npm test'        # Run command after creation
```

--------------------------------

### Zsh: Download Helper and Define 'jt' Alias

Source: https://chmouel.github.io/lazyworktree/docs/shell-integration

Download the Zsh helper functions and add them to your .zshrc, then define a 'jt' command for jumping to worktrees.

```zsh
mkdir -p ~/.shell/functions
curl -sL https://raw.githubusercontent.com/chmouel/lazyworktree/refs/heads/main/shell/functions.zsh -o ~/.shell/functions/lazyworktree.zsh

# Add to .zshrc
source ~/.shell/functions/lazyworktree.zsh

jt() { worktree_jump $(git rev-parse --show-toplevel) "$@"; }
```

--------------------------------

### Bash: Download Helper and Define 'jt' Alias

Source: https://chmouel.github.io/lazyworktree/docs/shell-integration

Download the Bash helper functions and add them to your .bashrc, then define a 'jt' command for jumping to worktrees.

```bash
mkdir -p ~/.shell/functions
curl -sL https://raw.githubusercontent.com/chmouel/lazyworktree/refs/heads/main/shell/functions.bash -o ~/.shell/functions/lazyworktree.bash

# Add to .bashrc
source ~/.shell/functions/lazyworktree.bash

jt() { worktree_jump $(git rev-parse --show-toplevel) "$@"; }
```

--------------------------------

### Container with zellij

Source: https://chmouel.github.io/lazyworktree/docs/guides/container-execution

Combine container execution with zellij. Each zellij window runs within the same specified container image. The worktree is automatically mounted.

```yaml
custom_commands:
  ctrl+z:
    description: Node dev container
    zellij:
      session_name: "dev:$WORKTREE_NAME"
      windows:
        - name: server
          command: "npm run dev"
        - name: test
          command: "npm test"
        - name: shell
    container:
      image: "node:20"

```

--------------------------------

### List Worktrees using Alias

Source: https://chmouel.github.io/lazyworktree/docs/cli/list

Demonstrates the use of the `ls` alias for the `list` command, providing the same default table output.

```bash
lazyworktree ls
```

--------------------------------

### create

Source: https://chmouel.github.io/lazyworktree/docs/cli/commands

Create a new worktree with various options for naming, branching, issue/PR integration, and metadata.

```APIDOC
## create

Create a new worktree

### Arguments
- `[worktree-name]`

### Flags
- `--description` (string): Set a description on the new worktree
- `--exec`, `-x` (string): Run a shell command after creation (in the created worktree, or current directory with --no-workspace)
- `--exec-mode` (string): Shell invocation mode for --exec: direct|shell|login-shell (default: login-shell)
- `--from-branch`, `--branch` (string): Create worktree from branch (defaults to current branch)
- `--from-issue` (int): Create worktree from issue number
- `--from-issue-interactive`, `-I` (bool): Interactively select an issue to create worktree from
- `--from-pr` (int): Create worktree from PR number
- `--from-pr-interactive`, `-P` (bool): Interactively select a PR to create worktree from
- `--generate` (bool): Generate name automatically from the current branch
- `--json` (bool): Output result as JSON
- `--no-workspace`, `-N` (bool): Create local branch and switch to it without creating a worktree (requires --from-pr, --from-pr-interactive, --from-issue, or --from-issue-interactive)
- `--note` (string): Set a note on the new worktree
- `--note-file` (string): Read note from file (use '-' for stdin)
- `--output-selection` (string): Write created worktree path to a file
- `--query`, `-q` (string): Pre-filter interactive selection (pre-fills fzf search or filters numbered list); requires --from-pr-interactive or --from-issue-interactive
- `--silent` (bool): Suppress progress messages
- `--tags` (string): Comma-separated tags for the new worktree
- `--with-change` (bool): Carry over uncommitted changes to the new worktree
```

--------------------------------

### Create Worktree with Executable Command

Source: https://chmouel.github.io/lazyworktree/docs/cli/create

Creates a worktree and executes a specified command after successful creation. The command can be run in the default login shell mode or a direct execution mode.

```bash
lazyworktree create my-feature --exec 'npm test'
lazyworktree create my-feature --exec 'npm test' --exec-mode direct
```

--------------------------------

### LazyWorktree Runtime Shape

Source: https://chmouel.github.io/lazyworktree/docs/development/architecture

Illustrates the runtime flow from the command entrypoint through bootstrapping to either the TUI or CLI path, utilizing shared subsystems.

```text
cmd/lazyworktree/main.go
        |
        v
internal/bootstrap
  |-----------------------------|
  |                             |
  v                             v
TUI path                     CLI path
internal/app                 internal/cli
  |                             |
  |---- uses shared subsystems --|
                |
                v
  internal/config / internal/git / internal/security
  internal/theme  / internal/multiplexer / internal/models

```

--------------------------------

### Configure Automatically Generated Notes

Source: https://chmouel.github.io/lazyworktree/docs/core/notes-and-taskboard

Specify a script to prefill notes when creating worktrees from PRs or issues. The script receives ticket data on stdin and outputs the note to stdout.

```shell
worktree_note_script: "aichat -m gemini:gemini-2.5-flash-lite 'Summarise this ticket into practical implementation notes.'"

```

--------------------------------

### Define a Full Custom Theme

Source: https://chmouel.github.io/lazyworktree/docs/configuration/custom-themes

Create a completely new theme by defining all 11 required color keys. This provides full control over the theme's appearance. Ensure all hex color codes are in the correct format.

```yaml
custom_themes:
  completely-custom:
    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"

```

--------------------------------

### Launch Zellij Session via CLI

Source: https://chmouel.github.io/lazyworktree/docs/guides/multiplexer-integration

Execute Zellij sessions for a specific worktree using the `lazyworktree exec` command. Specify the key and workspace to launch the desired session.

```bash
# Launch zellij session
lazyworktree exec -k Z -w my-feature
```

--------------------------------

### Configure Synchronisable Notes (JSON)

Source: https://chmouel.github.io/lazyworktree/docs/core/notes-and-taskboard

Set a JSON file path to store all worktree notes in a single, shareable file. This path is relative to the repository root.

```yaml
worktree_notes_path: ".lazyworktree/notes.json"

```

--------------------------------

### Run Full Quality Pipeline

Source: https://chmouel.github.io/lazyworktree/docs/development/contributing

Execute the complete quality check, including linting, formatting, and testing. This command may modify files in your working tree.

```bash
make sanity

```

--------------------------------

### Auto-detect Worktree and Launch Session via CLI

Source: https://chmouel.github.io/lazyworktree/docs/guides/multiplexer-integration

Launch a multiplexer session by auto-detecting the worktree from the current directory. Navigate to the worktree directory and use the `lazyworktree exec` command.

```bash
# Auto-detect worktree from current directory
cd ~/worktrees/repo/my-feature
lazyworktree exec --key=t
```

--------------------------------

### Interactive Worktree Creation with Pre-filtering

Source: https://chmouel.github.io/lazyworktree/docs/cli/create

Pre-filter interactive issue or PR selection using a query string. This narrows down the choices presented during interactive selection.

```bash
lazyworktree create -P -q "dark"              # Pre-filter interactive PR selection
lazyworktree create -I --query "login"        # Pre-filter interactive issue selection
```

--------------------------------

### list

Source: https://chmouel.github.io/lazyworktree/docs/cli/commands

List all worktrees. Supports JSON output, filtering for main branch worktrees, and pristine path output.

```APIDOC
## list

List all worktrees

### Flags
- `--json` (bool): Output as JSON
- `--main`, `-m` (bool): Show only the main branch worktree
- `--no-agent` (bool): Skip agent session data in JSON output (faster for scripting)
- `--pristine`, `-p` (bool): Output paths only (one per line, suitable for scripting)
```

--------------------------------

### Describe a Specific Command

Source: https://chmouel.github.io/lazyworktree/docs/cli/describe

To describe a particular command, provide its name as an argument to `lazyworktree describe`. This will output the structure for that specific command.

```bash
# Describe a specific command
lazyworktree describe create
lazyworktree describe list
```

--------------------------------

### Introspect CLI Structure with describe

Source: https://chmouel.github.io/lazyworktree/docs/guides/ai-integration

Use `describe` to discover flags and subcommands programmatically. It emits stable JSON output and exits with 0 on success.

```bash
# Full CLI structure
lazyworktree describe | jq '.subcommands[].name'
```

```bash
# Flags for a specific command
lazyworktree describe create | jq '.flags[].name'
```

```bash
# Check a nested subcommand
lazyworktree describe note show | jq '.'
```

--------------------------------

### Configure Custom Pane Sizes

Source: https://chmouel.github.io/lazyworktree/docs/configuration/display-and-themes

Use `layout_sizes` to adjust the screen space allocated to different panes. Values are relative weights that are normalized during computation. Omitted fields retain their default settings.

```yaml
layout_sizes:
  worktrees: 45    # Main pane width (default) or height (top layout)
  info: 30         # Info pane share of secondary area
  git_status: 30   # Git status pane share (when visible)
  commit: 30       # Commit log pane share
  notes: 30        # Notes pane share (when visible)

```

--------------------------------

### Define Universal Custom Commands

Source: https://chmouel.github.io/lazyworktree/docs/custom-commands

Configure universal custom commands that can be triggered by keybindings. The `wait: true` option ensures the command completes before proceeding.

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

```

--------------------------------

### Configure Search and Input Behavior

Source: https://chmouel.github.io/lazyworktree/docs/configuration/refresh-and-performance

Adjust settings for search auto-selection, fuzzy finder suggestions, and command palette ordering. Control MRU limit for the command palette.

```yaml
search_auto_select: false    # Start with filter focused (default: false)
fuzzy_finder_input: true     # Fuzzy suggestions in input dialogues (default: true)
palette_mru: true            # Most-recently-used ordering in command palette (default: true)
palette_mru_limit: 10        # Number of recent entries to track (default: 10)
```

--------------------------------

### Run Specific Command in Container

Source: https://chmouel.github.io/lazyworktree/docs/guides/container-execution

Execute a specific command within the container. `show_output: true` displays the command's output. The worktree is mounted at `/workspace`.

```yaml
custom_commands:
  T:
    command: "go test ./..."
    description: Tests in container
    show_output: true
    container:
      image: "golang:1.22"

```

--------------------------------

### Configure Single Notes File for All Repositories

Source: https://chmouel.github.io/lazyworktree/docs/troubleshooting/faq

Set `worktree_notes_path` to consolidate all worktree notes into a single JSON file. This makes notes portable and shareable across machines and teams.

```yaml
worktree_notes_path: ".lazyworktree/notes.json"
```

--------------------------------

### Discover Flags for a Command

Source: https://chmouel.github.io/lazyworktree/docs/cli/describe

Use `lazyworktree describe` piped to `jq` to discover all flags for a specific command before invoking it. This helps in understanding available options and their types.

```bash
# Discover all flags for create before invoking it
lazyworktree describe create | jq '.flags[] | {name, type, usage}'
```

--------------------------------

### Configure Worktree Notes Type (Splitted)

Source: https://chmouel.github.io/lazyworktree/docs/worktree-notes

Use the `splitted` note type and set `worktree_notes_path` to store individual markdown files for each worktree note. These files include YAML frontmatter with metadata like icon, color, and timestamp.

```yaml
worktree_note_type: splitted
worktree_notes_path: "~/notes/$REPO_OWNER/$REPO_REPONAME/$WORKTREE_NAME.md"

```

--------------------------------

### Set Note from Standard Input

Source: https://chmouel.github.io/lazyworktree/docs/cli/note

Allows you to set the note content by piping text to the command's standard input. Use `-i -` to indicate that the input source is stdin.

```bash
echo "release prep" | lazyworktree note edit -i -
```

--------------------------------

### Listing Worktrees

Source: https://chmouel.github.io/lazyworktree/docs/cli

List worktrees in different formats: table (default), paths only for scripting, or JSON output. 'ls' is an alias for 'list'.

```bash
lazyworktree list              # Table output (default)
```

```bash
lazyworktree list --pristine   # Paths only (scripting)
```

```bash
lazyworktree list --json       # JSON output
```

```bash
lazyworktree ls                # Alias
```

--------------------------------

### Configure Session Prefix

Source: https://chmouel.github.io/lazyworktree/docs/guides/multiplexer-integration

Set a prefix to filter which sessions appear in the command palette. Use a unique prefix like `wt-` to distinguish LazyWorktree sessions.

```yaml
session_prefix: "wt-"
```

--------------------------------

### List Git Configured Keys with lw. Prefix

Source: https://chmouel.github.io/lazyworktree/docs/configuration/overview

Retrieve all LazyWorktree specific configuration keys (prefixed with 'lw.') from Git's global or local configuration.

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

--------------------------------

### Show Command Output

Source: https://chmouel.github.io/lazyworktree/docs/custom-commands

Configure a command to display its standard output and error in a pager. This is useful for commands like `git status`.

```yaml
custom_commands:
  universal:
    o:
      command: git status -sb
      description: Status
      show_output: true

```

--------------------------------

### Test AI Branch Naming Script Manually

Source: https://chmouel.github.io/lazyworktree/docs/guides/ai-integration

Manually test your configured AI script by echoing sample PR title and description to its standard input.

```bash
echo "Test PR title\n\nTest description" | aichat -m gemini:gemini-2.5-flash-lite 'Generate a branch name'
```

--------------------------------

### tmux Multi-Window Session Configuration

Source: https://chmouel.github.io/lazyworktree/docs/guides/multiplexer-integration

Set up a tmux session with multiple pre-defined windows, each running a specific command and working directory. This is useful for complex development workflows.

```yaml
custom_commands:
  t:
    description: Tmux with layout
    show_help: true
    tmux:
      session_name: "wt:$WORKTREE_NAME"
      attach: true
      on_exists: switch
      windows:
        - name: editor
          command: nvim
        - name: shell
          command: zsh
        - name: lazygit
          command: lazygit
        - name: tests
          command: npm run test:watch
          cwd: $WORKTREE_PATH/tests

```

--------------------------------

### Show Note for Current Worktree

Source: https://chmouel.github.io/lazyworktree/docs/cli/note

Prints the raw note text for the worktree detected in the current directory to standard output. This is useful for scripting and piping the output to other commands.

```bash
lazyworktree note show
```

--------------------------------

### Create Worktree with JSON Output

Source: https://chmouel.github.io/lazyworktree/docs/cli/create

Creates a worktree and outputs the result in JSON format for machine readability. Useful for scripting and automation.

```bash
lazyworktree create my-feature --json         # Machine-readable output
```

--------------------------------

### Switch to Plain-Text Icons

Source: https://chmouel.github.io/lazyworktree/docs/troubleshooting/fonts-and-rendering

Use this setting to immediately switch to plain-text icons if symbols are rendering incorrectly. This is a quick fix for garbled glyphs.

```yaml
icon_set: text
```

--------------------------------

### Override Container Entrypoint

Source: https://chmouel.github.io/lazyworktree/docs/guides/container-execution

Override the image's default entrypoint to run a specific binary, such as a shell. Useful for images bundling multiple tools. The worktree is mounted at `/workspace`.

```yaml
custom_commands:
  ctrl+s:
    description: Shell in Python container
    container:
      image: "python:3.12"
      entrypoint: "/bin/sh"
      interactive: true

```

--------------------------------

### List Worktrees in Pristine Format

Source: https://chmouel.github.io/lazyworktree/docs/cli/list

Outputs only the paths of the available worktrees, one per line. This format is ideal for use in shell pipelines and scripting.

```bash
lazyworktree list --pristine
```

--------------------------------

### exec

Source: https://chmouel.github.io/lazyworktree/docs/cli/commands

Run a command or trigger a key action in a worktree. Supports JSON output, custom command keys, and specifying target worktrees.

```APIDOC
## exec

Run a command or trigger a key action in a worktree

### Arguments
- `[command]`

### Flags
- `--json` (bool): Output result as JSON; command stdout/stderr is redirected to stderr
- `--key`, `-k` (string): Custom command key to trigger (e.g. 't' for tmux)
- `--workspace`, `-w` (string): Target worktree name or path
```

--------------------------------

### Configure AI for Ticket Summarization

Source: https://chmouel.github.io/lazyworktree/docs/guides/ai-integration

Set the `worktree_note_script` to use aichat with a specific model for summarizing ticket content.

```yaml
worktree_note_script: "aichat -m gemini:gemini-2.5-flash-lite 'Summarise this ticket into practical implementation notes.'"
```

--------------------------------

### Fish: Function for Jumping to Last Selected Worktree

Source: https://chmouel.github.io/lazyworktree/docs/shell-integration

Define a 'pl' function in Fish to quickly jump to the last selected worktree.

```fish
function pl
    worktree_go_last $(git rev-parse --show-toplevel)
end
```

--------------------------------

### Enable Debug Logging via CLI Flag

Source: https://chmouel.github.io/lazyworktree/docs/troubleshooting/diagnostic-guide

Use this command to enable debug logging and specify the output file path. This captures internal decisions, git commands, API calls, and timing information.

```bash
lazyworktree --debug-log /tmp/lw-debug.log

```