Skip to main content
Define custom keybindings that run commands in the selected worktree. Commands run interactively (TUI suspends) and appear in the command palette.
Custom commands take precedence over built-in keys. For example, defining a custom s command will override the built-in sort toggle.

​
Default Commands

LazyWorktree includes two default custom commands:
  • t - Create/attach to tmux session
  • Z - Create/attach to zellij session
You can override these by defining custom_commands.t or custom_commands.Z in your config.

​
Configuration Format

Define commands in your config.yaml: 
custom_commands:
  e:
    command: nvim
    description: Editor
    show_help: true
  
  s:
    command: zsh
    description: Shell
    show_help: true
  
  l:
    command: ls -la
    description: List files
    show_help: true
    wait: true

​
Field Reference

​
command
string
required
The command to execute. Can include environment variables.Example: make test, git status -sb, nvim
​
description
string
default:""
Description shown in help screen and command palette.
​
show_help
boolean
default:false
Show in help screen (triggered with ?) and footer hints.
​
wait
boolean
default:false
Wait for keypress after command completes. Useful for quick commands where you want to see output before returning to TUI.
​
show_output
boolean
default:false
Display command output in the pager instead of running interactively. When true, stdout/stderr are captured and shown in the configured pager. Ignores wait setting.Example use case: git status, git log, or other read-only commands
​
new_tab
boolean
default:false
Launch command in a new terminal tab. Works with Kitty (with remote control enabled), WezTerm, and iTerm. Can be combined with tmux or zellij configuration.
​
tmux
object
Configure tmux session for this command. See Tmux Configuration below.
​
zellij
object
Configure zellij session for this command. See Zellij Configuration below.

​
Environment Variables

All commands have access to these environment variables:
VariableDescriptionExample
WORKTREE_PATHPath to the worktree/home/user/.local/share/worktrees/org-repo/feature-x
WORKTREE_BRANCHGit branch namefeature-x
WORKTREE_NAMEWorktree directory namefeature-x
MAIN_WORKTREE_PATHMain repository path/home/user/projects/repo
REPO_NAMERepository identifierchmouel-lazyworktree

​
Example Usage

custom_commands:
  e:
    command: echo "Working in $WORKTREE_NAME on branch $WORKTREE_BRANCH"
    description: Show info
    show_help: true
    wait: true

​
Tmux Configuration

Create or attach to tmux sessions with multiple windows: 
custom_commands:
  t:
    description: Tmux session
    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

​
Tmux Fields

​
tmux.session_name
string
default:"wt:$WORKTREE_NAME"
Session name. Environment variables are expanded. Special characters are replaced with hyphens.
​
tmux.attach
boolean
default:true
Attach immediately to the session. If false, shows a modal with attachment instructions.
​
tmux.on_exists
string
default:"switch"
Behaviour when session already exists.Options:
  • switch - Switch to existing session
  • attach - Attach to existing session
  • kill - Kill existing session and create new one
  • new - Create new session with incremented name
​
tmux.windows
array
Window definitions for the session. If empty, creates a single “shell” window.

​
Tmux Window Fields

​
windows[].name
string
default:"window-N"
Window name. Supports environment variables.
​
windows[].command
string
default:""
Command to run in the window. Empty uses your default shell.
​
windows[].cwd
string
default:"$WORKTREE_PATH"
Working directory for the window. Supports environment variables.

​
Zellij Configuration

Create or attach to zellij sessions with multiple tabs: 
custom_commands:
  Z:
    description: Zellij session
    show_help: true
    zellij:
      session_name: "wt:$WORKTREE_NAME"
      attach: true
      on_exists: switch
      windows:
        - name: claude
          command: claude
        - name: shell
          command: zsh
        - name: lazygit
          command: lazygit

​
Zellij Fields

​
zellij.session_name
string
default:"wt:$WORKTREE_NAME"
Session name. Environment variables are expanded. Characters /, \, : are replaced with hyphens.
​
zellij.attach
boolean
default:true
Attach immediately to the session. If false, shows a modal with attachment instructions.
​
zellij.on_exists
string
default:"switch"
Behaviour when session already exists.Options:
  • switch - Switch to existing session
  • attach - Attach to existing session
  • kill - Kill existing session and create new one
  • new - Create new session with incremented name
​
zellij.windows
array
Tab definitions for the session. If empty, creates a single “shell” tab.

​
Zellij Window Fields

​
windows[].name
string
default:"window-N"
Tab name. Supports environment variables.
​
windows[].command
string
default:""
Command to run in the tab. Empty uses your default shell.
​
windows[].cwd
string
default:"$WORKTREE_PATH"
Working directory for the tab. Supports environment variables.

​
Key Formats

Supported key formats:

​
Single Keys

custom_commands:
  e:    # Letter e
    command: nvim
  
  s:    # Letter s
    command: zsh
  
  T:    # Capital T (Shift+T)
    command: make test

​
Modifier Combinations

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
  
  "ctrl+shift+s":
    command: git status -sb
    description: Git status
    show_output: true

​
Special Keys

custom_commands:
  enter:
    command: git status
  
  esc:
    command: echo "Escape pressed"
  
  tab:
    command: ls -la
  
  space:
    command: make build

​
Complete Examples

​
Simple Commands

custom_commands:
  s:
    command: zsh
    description: Open shell
    show_help: true
  
  t:
    command: make test
    description: Run tests
    show_help: false
    wait: true
  
  l:
    command: ls -la
    description: List files
    show_help: true
    wait: true
  
  "ctrl+t":
    command: git status -sb
    description: Status
    show_help: true
    show_output: true

​
Tmux Session with Multiple Windows

custom_commands:
  T:
    description: Development session
    show_help: true
    tmux:
      session_name: "dev:$WORKTREE_NAME"
      attach: true
      on_exists: switch
      windows:
        - name: editor
          command: nvim
        - name: shell
          command: zsh
        - name: tests
          command: npm run test:watch
        - name: server
          command: npm run dev

​
Zellij Session with Custom Working Directories

custom_commands:
  Z:
    description: Zellij workspace
    show_help: true
    zellij:
      session_name: "work:$WORKTREE_BRANCH"
      attach: true
      on_exists: switch
      windows:
        - name: editor
          command: nvim
          cwd: $WORKTREE_PATH/src
        - name: tests
          command: npm test
          cwd: $WORKTREE_PATH
        - name: docs
          command: zsh
          cwd: $WORKTREE_PATH/docs

​
Open in New Terminal Tab

custom_commands:
  c:
    command: claude
    description: Claude Code
    new_tab: true
    show_help: true
  
  "ctrl+c":
    command: code .
    description: VS Code
    new_tab: true
The new_tab feature requires:
  • Kitty with remote control enabled
  • WezTerm
  • iTerm

​
Show Output in Pager

custom_commands:
  "ctrl+l":
    command: git log --oneline -20
    description: Recent commits
    show_help: true
    show_output: true
  
  "ctrl+d":
    command: git diff
    description: Show diff
    show_help: true
    show_output: true

​
Session Prefix

The command palette lists tmux/zellij sessions matching the session_prefix (default: wt-): 
session_prefix: "wt-"
Change this if you use a different naming convention: 
session_prefix: "dev-"

​
Key Precedence

Custom commands override built-in keys. If you define a custom s command, the built-in sort toggle will no longer work on the s key.
Built-in keys that are commonly overridden:
  • s - Sort mode toggle
  • t - Default tmux command
  • Z - Default zellij command
  • l - Layout toggle
Consider using modifier combinations (like ctrl+s) to avoid conflicts with built-in keys.

Build docs developers (and LLMs) love

Get started for freeTalk to us