Config Reference

pertmux uses a TOML configuration file. It looks for ~/.config/pertmux.toml by default, or you can specify a path with -c:

pertmux -c ./path/to/config.toml serve

Global options

Key	Type	Default	Description
refresh_interval	integer	2	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	30	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.

[gitlab]

Key	Type	Default	Description
host	string	gitlab.com	GitLab instance hostname
token	string	—	Personal access token (or set PERTMUX_GITLAB_TOKEN env var)

[github]

Key	Type	Default	Description
host	string	github.com	GitHub hostname (use custom host for GitHub Enterprise)
token	string	—	Personal access token (or set PERTMUX_GITHUB_TOKEN env var). Needs repo scope for private repos.

[[project]]

Key	Type	Required	Description
name	string	yes	Display name (shown in overview)
source	string	yes	"gitlab" or "github"
project	string	yes	Full project path (e.g. team/app or org/repo)
local_path	string	yes	Absolute path to local repo (validated at startup)
username	string	no	Your username (for filtering MRs/PRs to your own)

[agent.opencode]

Including this section enables the opencode agent. Omit or comment it out to disable.

Key	Type	Default	Description
db_path	string	~/.local/share/opencode/opencode.db	Path to the opencode SQLite database

[agent.claude_code]

Including this section enables the Claude Code agent. No configuration options needed.

[agent.codex]

Including this section enables the Codex CLI agent. Omit or comment it out to disable.

Key	Type	Default	Description
codex_home	string	~/.codex	Override the Codex home directory (contains state_5.sqlite and logs_2.sqlite)

[keybindings]

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

[[agent_action]]

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.

Environment variables

Variable	Overrides	Description
PERTMUX_GITLAB_TOKEN	[gitlab].token	GitLab personal access token
PERTMUX_GITHUB_TOKEN	[github].token	GitHub personal access token