pertmux uses a TOML configuration file. It looks for ~/.config/pertmux.toml by default, or you can specify a path with -c:
Terminal window
pertmux-c./path/to/config.tomlserve
The daemon checks the active config file for changes once per second. Valid edits are applied
automatically, including projects, agents, refresh intervals, actions, and keybindings. If an edit
does not parse or validate, pertmux keeps the last working configuration and reports the error;
saving a corrected file triggers another reload attempt.
How often (in seconds) to poll tmux panes and agent status
mr_detail_interval
integer
60
How often (in seconds) to refresh MR detail and pipeline status
worktree_interval
integer
300
How often (in seconds) to refresh worktree list
mr_list_interval
integer
300
How often (in seconds) to refresh the MR/PR list from the forge
default_agent_command
string
—
Command to run in a split pane when focusing a worktree (e.g. "opencode")
default_worktree_with_prompt
string
—
Command template for creating a worktree with an injected prompt. Use {{msg}} as the placeholder (e.g. "opencode run {{msg}}"). Enables the w keybinding — see Worktree with Prompt.
Remap action keys. Navigation keys (j/k/↑/↓/Tab/Enter/Esc/q) are not configurable. Each action must have a unique key — duplicates are rejected at startup with a clear error message.
Key
Type
Default
Description
refresh
string
"r"
Refresh all data
open_browser
string
"o"
Open selected MR in browser
copy_branch
string
"b"
Copy selected branch name to clipboard
filter_projects
string
"f"
Fuzzy filter to switch project
create_worktree
string
"c"
Create new worktree
open_worktree_with_prompt
string
"w"
Create worktree and inject a prompt into the agent (requires default_worktree_with_prompt)
delete_worktree
string
"d"
Delete selected worktree
merge_worktree
string
"M"
Merge selected worktree into default branch
mr_overview
string
"m"
Open MR Overview popup (all your open MRs across all forges)
agent_actions
string
"a"
Open agent actions panel
activity_feed
string
"A"
Open Activity Feed popup — navigate recent events and jump to the relevant pane or MR
Define custom agent actions that can be sent to coding agent instances from the dashboard. When any [[agent_action]] entries are present, they replace the built-in defaults. Omit this section entirely to use the two default actions (rebase, pipeline fix).
Key
Type
Required
Default
Description
name
string
yes
—
Display name shown in the actions popup
prompt
string
yes
—
Prompt template sent to the agent
requires_mr
boolean
no
false
If true, action is skipped when no MR is linked
Prompts support template variables: {target_branch}, {source_branch}, {mr_url}, {mr_iid}, {project_name}. See Agent Actions for details and examples.
