Configuration

The dashboard can be customized in your .workmux.yaml:

dashboard:
  commit: "Commit staged changes with a descriptive message"
  merge: "!workmux merge"
  layout: stacked
  preview_size: 60
  agent_columns:
    [number, project, worktree, git, pr, window, status, time, title]
  worktree_columns: [number, project, worktree, git, pr, mux, age, agent]
  close_on_jump: true
  input_exit_key: Esc

The commit and merge values are text sent to the agent’s pane. Use the ! prefix to run shell commands (supported by Claude, Gemini, and other agents).

Defaults

Option	Default value	Description
commit	Commit staged changes with a descriptive message	Natural language prompt
merge	!workmux merge	Shell command via agent
layout	stacked	stacked (table above preview) or side_by_side (preview left, table right)
preview_size	60	Preview height or width as percentage (10-90)
agent_columns	[number, project, worktree, git, pr, status, time, title]	Agents table columns, in display order
worktree_columns	[number, project, worktree, git, pr, mux, age, agent]	Worktree table columns, in display order
close_on_jump	true	Close the dashboard after a jump
input_exit_key	Esc	Key to exit input mode (Esc or Ctrl+<letter>)

Input mode exit key

input_exit_key accepts Esc (the default) or Ctrl+<letter> (a–z), case-insensitively. For example, to exit input mode with Ctrl+q and send Esc to the agent:

dashboard:
  input_exit_key: Ctrl+q

The exit key is consumed by the dashboard, not sent to the agent. Escape bindings in other dashboard modes are unchanged. Project configuration overrides the global setting.

Choose a key your terminal delivers distinctly. Some Ctrl-letter keys are indistinguishable from Tab, Enter, or Backspace, and terminal flow control can intercept Ctrl+q or Ctrl+s.

Staying open after a jump

Jumping to an agent or worktree closes the dashboard. This includes Enter, 1-9, Bksp, command-palette jumps, and double-clicking a row. Set close_on_jump: false to keep the dashboard open while moving between agents and worktrees:

dashboard:
  close_on_jump: false

The jump still updates the pane history used by Bksp. The p peek action always keeps the dashboard open and does not update pane history. Multiplexers such as Zellij that keep the dashboard open after jumps retain that behavior regardless of this setting.

Columns

agent_columns sets which columns the agents table shows and in what order. For example, to read the title first and keep the elapsed time out of the way:

dashboard:
  agent_columns:
    [number, window, status, title, project, worktree, git, pr, time]

Column	Content
number	Jump key of the row, shown under the # header
project	Project name
worktree	Worktree name, with a pane number when it splits
git	Branch state, staged and unstaged changes
pr	Pull request number and check status
pr_title	Pull request title
pr_issues	Issues closed by the pull request
window	Multiplexer window index
status	Agent status icons
time	Time since the last status change
title	Agent session title
prompt	Latest prompt you sent to the agent

A column left out of the list is not rendered, so agent_columns: [worktree, status, title] gives a table of just those three. Repeating a column has no effect, and an empty list falls back to the default order.

Dropping number hides the jump key, and 1-9 still jump to the first nine rows. The pr column appears only while at least one agent has a pull request or checks to report, wherever it is placed in the list. The opt-in pr_title and pr_issues columns stay visible and leave the cell blank when the branch has no pull request or closing issues. pr_issues uses GitHub’s closing issue references, not arbitrary issue mentions in pull request text. Same-repository issues appear as #123; cross-repository issues include the repository, such as owner/repo#123. The opt-in window column shows the tmux window index used by prefix + <n>; backends without window indexes leave the cell blank. A trailing title, prompt, pr_title, or pr_issues takes the width left over by the other columns; anywhere else it sizes to its content, and the leftover width sits at the right edge of the table.

Prompt column

The opt-in prompt column shows the last prompt you sent to each agent, on one line and cut with … to fit. Status hooks store the prompt only while the prompt column or a {prompt} sidebar token is configured, evaluated with the agent’s project configuration. Removing both stops capture, and each agent’s stored prompt is deleted at its next status update.

Prompts come from Claude Code, Codex, Gemini CLI, Copilot CLI, Grok, OpenCode, pi, and oh-my-pi. Prompts sent to subagents and messages the agent injects itself are ignored. A prompt with no text, such as an image alone, keeps the previous prompt. A prompt passed when the agent starts, such as workmux add -p, may not be shown until you send the next one. OpenCode, pi, and oh-my-pi report prompts once workmux setup updates their status plugin.

Worktree columns

worktree_columns controls the Worktrees tab independently of agent_columns. To hide Git status and give the other columns more room:

dashboard:
  worktree_columns: [number, project, worktree, pr, mux, age, agent]

Column	Content
number	Jump key of the row, shown under the # header
project	Project name
worktree	Worktree name, with the branch when different
git	Branch state and uncommitted changes
pr	Pull request number and check status
pr_title	Pull request title
pr_issues	Issues closed by the pull request
mux	Whether a multiplexer window is open
age	Time since worktree creation
agent	Agent status summary

The list sets display order; omitted columns are hidden and duplicates are ignored. An absent or empty list uses the default order. Project configuration overrides the global list, and an explicit empty project list resets it to defaults.

A trailing agent, pr_title, or pr_issues fills the remaining width. Elsewhere it sizes to its content, leaving extra space at the right edge. The pr column is hidden until a worktree has a pull request or checks, except when it is the only configured column: like the agents table, it stays visible to avoid an empty table. The opt-in PR metadata columns use the same closing-reference and blank-cell behavior as the Agents table.

Hiding number does not disable 1-9 jumps. Hiding git does not disable Git status updates or remove the selected worktree’s Git details from the preview.

Layout

The default stacked layout places the table above the preview. To give the preview the full content height, with the table on the right:

dashboard:
  layout: side_by_side

The layout applies to both the Agents and Worktrees tabs. The tab header and footer remain above and below the content. Backends without preview support show only the table regardless of this setting.

Side-by-side leaves less width for each pane. On narrow terminals, use the stacked layout or reduce the table’s configured columns. Captured agent output is clipped to the preview width, not rewrapped.

Preview size

The preview_size option controls the preview as a percentage of the content area: height in stacked layout, width in side_by_side layout. A higher value means more space for the preview and less for the table.

You can also adjust the preview size interactively with +/- keys. These adjustments persist across dashboard sessions in the workmux state directory.

The CLI flag --preview-size (-P) overrides both the config and saved preference for that session.

Examples

# Use Claude skill for merge (see skills guide)
dashboard:
  merge: "/merge"

# Custom shell commands
dashboard:
  merge: "!workmux merge --rebase --notification"

# Natural language prompts
dashboard:
  commit: "Create a commit with a conventional commit message"
  merge: "Rebase onto main and run workmux merge"

Using skills

For complex workflows, skills are more powerful than simple prompts or shell commands. A skill can encode detailed, multi-step instructions that the agent follows intelligently.

dashboard:
  merge: "/merge"

See the skills guide for the /merge skill you can copy.