Skip to main content
LazyWorktree’s custom command system lets you define keybindings that execute commands, manage tmux/zellij sessions, and create per-repository workflows.

​
Configuration Format

Define custom commands in ~/.config/lazyworktree/config.yaml: 
custom_commands:
  e:
    command: nvim
    description: Editor
    show_help: true

​
Field Reference

FieldTypeDefaultDescription
commandstringrequiredCommand to execute
descriptionstring""Shown in help and palette
show_helpboolfalseShow in help screen (?) and footer
waitboolfalseWait for keypress after completion
show_outputboolfalseShow stdout/stderr in pager (ignores wait)
new_tabboolfalseLaunch in new terminal tab (Kitty, WezTerm, iTerm)
tmuxobjectnullConfigure tmux session
zellijobjectnullConfigure zellij session

​
Interactive TUI Suspension

Commands run interactively, suspending the TUI. After execution, LazyWorktree resumes. 
custom_commands:
  s:
    command: zsh
    description: Shell
    show_help: true
Set wait: true to pause after command completion, useful for reviewing output before returning to the TUI.

​
Environment Variables

Custom commands have access to worktree environment variables:
  • WORKTREE_BRANCH - Current worktree’s branch name
  • WORKTREE_PATH - Absolute path to worktree directory
  • WORKTREE_NAME - Worktree directory name
  • MAIN_WORKTREE_PATH - Path to main worktree
  • REPO_NAME - Repository name
custom_commands:
  b:
    command: echo "Branch: $WORKTREE_BRANCH in $WORKTREE_PATH"
    description: Show branch info
    show_output: true

​
tmux Session Management

Define tmux session layouts with multiple windows: 
custom_commands:
  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

​
tmux Fields

FieldTypeDefaultDescription
session_namestringwt:$WORKTREE_NAMESession name (env vars supported, special chars replaced)
attachbooltrueAttach immediately; if false, show modal with instructions
on_existsstringswitchBehaviour if session exists: switch, attach, kill, new
windowslist[ { name: "shell" } ]Window definitions for the session

​
tmux Window Fields

FieldTypeDefaultDescription
namestringwindow-NWindow name (supports env vars)
commandstring""Command to run in the window (empty uses default shell)
cwdstring$WORKTREE_PATHWorking directory for the window (supports env vars)
If windows is empty, creates a single shell window.

​
on_exists Behaviour

  • switch - Switch to existing session (default)
  • attach - Attach to existing session
  • kill - Kill existing session and create new
  • new - Create new session with incremented name (e.g., wt:feature-1)

​
zellij Session Management

Define zellij session layouts with multiple tabs: 
custom_commands:
  z:
    description: Zellij
    show_help: true
    zellij:
      session_name: "wt:$WORKTREE_NAME"
      attach: true
      on_exists: switch
      windows:
        - name: editor
          command: nvim
        - name: shell
          command: zsh
        - name: tests
          command: npm test -- --watch

​
zellij Fields

FieldTypeDefaultDescription
session_namestringwt:$WORKTREE_NAMESession name (env vars supported, special chars replaced)
attachbooltrueAttach immediately; if false, show modal with instructions
on_existsstringswitchBehaviour if session exists: switch, attach, kill, new
windowslist[ { name: "shell" } ]Tab definitions for the session

​
zellij Window Fields

FieldTypeDefaultDescription
namestringwindow-NTab name (supports env vars)
commandstring""Command to run in the tab (empty uses default shell)
cwdstring$WORKTREE_PATHWorking directory for the tab (supports env vars)
Session names with /, \, : are replaced with - for filesystem compatibility.

​
Terminal Tab Commands

Launch commands in a new terminal tab (Kitty, WezTerm, iTerm): 
custom_commands:
  c:
    command: claude
    description: Claude Code
    new_tab: true
    show_help: true
new_tab requires:
  • Kitty with remote control enabled
  • WezTerm
  • iTerm2
Other terminals are not supported.

​
Supported Key Formats

Custom commands support:
  • Single keys: e, s, T
  • Modifiers: ctrl+e, alt+t
  • Special keys: enter, esc, tab, space
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 override built-in keys. Use caution when redefining core bindings.

​
Default tmux/zellij Bindings

LazyWorktree provides default bindings:
  • t - tmux session
  • Z - zellij session
Override via custom_commands.t or custom_commands.Z.

​
Session Prefix

Configure the session name prefix: 
session_prefix: "wt-"  # Default: "wt-"
The command palette filters sessions by this prefix.

​
Command Palette Integration

Custom commands appear in the command palette (press Ctrl+p or :). Enable MRU (Most Recently Used) sorting: 
palette_mru: true         # Enable MRU sorting (default: true)
palette_mru_limit: 5      # Number of recent commands to show (default: 5)
Recently used commands appear at the top of the palette for quick access.

​
Real-World Examples

​
Run Tests

custom_commands:
  t:
    command: make test
    description: Run tests
    show_help: true
    wait: true

​
Open Editor

custom_commands:
  e:
    command: nvim
    description: Editor
    show_help: true

​
Claude Code in New Tab

custom_commands:
  c:
    command: claude
    description: Claude Code
    new_tab: true
    show_help: true

​
tmux Session with Multiple Windows

custom_commands:
  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

​
Show Git Status in Pager

custom_commands:
  o:
    command: git status -sb
    description: Status
    show_help: true
    show_output: true

Build docs developers (and LLMs) love

Get started for freeTalk to us