Worktree Management

pertmux integrates with worktrunk (wt) to provide full worktree lifecycle management from within the TUI.

Prerequisites

Install worktrunk and ensure wt is on your PATH:

cargo install worktrunk

Worktree panel

The worktree panel is rendered at the top of the dashboard, with the MR list below it. The worktree panel is default focused when you open the dashboard.

Each worktree card shows:

• Branch name with ahead/behind indicators
• Last commit message
• Commit age (e.g., “2h ago”, “3d ago”)
• Git status symbols (modified, staged, untracked files)

Actions

Key	Action
Tab	Switch between worktree panel and MR list
c	Create a new worktree
w	Create a new worktree and inject a prompt into the agent
d	Delete selected worktree
M	Merge selected worktree into the default branch
Enter	Jump to the worktree’s tmux pane

Create workflow

When you press c, pertmux opens a popup dialog where you enter the branch name. It then runs wt create to:

1. Show an in-progress toast (“Creating worktree…”)
2. Create a new worktree directory
3. Create and checkout the branch
4. Automatically refresh the dashboard (MR linking updates immediately)

Create with prompt {#create-with-prompt}

When default_worktree_with_prompt is set in your config, pressing w opens a two-field dialog:

1. Branch name — the git branch to create
2. Message — the prompt to inject into the agent command

pertmux substitutes your message into the {{msg}} placeholder of the template, then:

1. Creates the worktree (same as c)
2. Opens a split tmux pane running the filled command (e.g. opencode run implement the feature)

Configuration

pertmux.toml

default_worktree_with_prompt = "opencode run {{msg}}"

The {{msg}} placeholder is replaced with the message you type in the dialog. The resulting command is run in the left pane of a horizontal tmux split; the right pane opens an empty terminal in the worktree directory.

Example

With default_worktree_with_prompt = "opencode run {{msg}}":

• Press w in the worktrees panel
• Enter branch name: feat/login-page
• Enter message: implement the user login page with email and password fields
• Press Enter

pertmux creates the feat/login-page worktree and opens a tmux pane running:

opencode run implement the user login page with email and password fields

Merge workflow

Press M on a worktree to merge it into the default branch. pertmux runs wt merge which:

1. Show an in-progress toast (“Merging worktree…”)
2. Merges the branch into the default branch
3. Cleans up the worktree directory
4. Removes the local branch
5. Automatically refresh the dashboard

Split pane with agent

When the default_agent_command is set in your config, pressing Enter on a worktree creates a horizontal split in tmux:

• Left pane: Runs the specified agent command (e.g., opencode)
• Right pane: Opens an empty terminal in the worktree directory

This allows you to start working with an agent immediately upon focusing a worktree.