GitHub - rupert648/pertmux: pertmux ([ru]-pert multiplexer) - unified SWE Dash

pertmux ([ru]-pert multiplexer) is a unified SWE dashboard that links GitLab/GitHub MRs to local branches/worktrees, tmux sessions, and coding agent instances. It provides a real-time view of merge request status, pipeline health, worktree management, and session progress — all from a single TUI.

Features

• Multi-forge support — GitLab and GitHub MR/PR tracking with pipeline dots, comments, and unread indicators
• Worktree management — list, create, remove, and merge worktrees via worktrunk
• Multi-project support — fuzzy finder (f key) with overview panel showing MR counts
• Smart tmux integration — focus panes across sessions, auto-detect existing windows
• Coding agent monitoring — track Claude/opencode instances across tmux panes
• MR Overview — press m to see all your open MRs across all configured forges, with quick navigation to configured projects or browser-open for unconfigured ones
• Activity feed — live log of agent state changes and MR events; press A to open the feed popup, navigate with j/k, and press Enter to jump directly to the relevant tmux pane or MR
• Daemon/client architecture — background daemon keeps data fresh, TUI client connects instantly via Unix socket

Architecture

┌─────────────────────────────────────────────────────────┐
│                    pertmux serve                        │
│                     (daemon)                            │
│                                                         │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐   ┌─────────┐  │
│  │  tmux   │  │  Forge   │  │ worktrunk│   │  agent  │  │
│  │  poll   │  │   API    │  │   CLI    │   │  status │  │
│  │  (2s)   │  │  (60s)   │  │  (30s)   │   │  (2s)   │  │
│  └────┬────┘  └────┬─────┘  └────┬─────┘   └────┬────┘  │
│       └─────────┬──┴─────────────┴──────────────┘       │
│                 ▼                                       │
│         DashboardSnapshot                               │
│                 │                                       │
│    Unix socket  │  /tmp/pertmux-{USER}.sock             │
└─────────────────┼───────────────────────────────────────┘
                  │  broadcast (multi-client)
        ┌─────────┼─────────┐
        ▼         ▼         ▼
   ┌─────────┐ ┌─────────┐ ┌─────────┐
   │ connect │ │ connect │ │ connect │
   │ (TUI)   │ │ (TUI)   │ │ (TUI)   │
   └─────────�� └─────────┘ └─────────┘

Setup

Prerequisites

• tmux 3.2+ (for popup support)
• worktrunk (optional) — enables the worktree management panel. Install with cargo install worktrunk and ensure wt is on your PATH.

Install

Or build from source:

git clone https://github.com/rupert648/pertmux.git
cd pertmux
cargo install --path .

tmux Integration

Add to your ~/.tmux.conf for a popup overlay (recommended):

# pertmux dashboard popup (prefix+a toggles open/close)
bind-key a display-popup -h 80% -w 80% -E "pertmux connect"

• prefix+a opens the TUI client, connecting to the running daemon
• prefix+a again closes the popup; next open reconnects instantly
• q/Esc quits the client (daemon keeps running)

Commands

pertmux serve                    # start daemon (backgrounds automatically)
pertmux connect                  # open TUI client (connects to running daemon)
pertmux stop                     # stop the daemon
pertmux status                   # show socket path, daemon state
pertmux --version                # show version
pertmux -c config.toml serve     # start daemon with specific config
pertmux serve --foreground       # run in foreground (for debugging)

The daemon must be started before connecting. It forks to the background automatically, logging to /tmp/pertmux-daemon.log and listening on /tmp/pertmux-{USER}.sock.

Configuration

pertmux works out of the box with zero configuration for basic agent monitoring. For GitLab/GitHub MR tracking and multi-project support, create a TOML config file.

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

If no -c flag is provided, pertmux looks for ~/.config/pertmux.toml. If that file doesn't exist, defaults are used.

Multi-project config (recommended)

[gitlab]
host = "gitlab.example.com"
token = "glpat-your-token-here"

[github]
token = "ghp_your-token-here"

[[project]]
name = "My App"
source = "gitlab"
project = "team/my-app"
local_path = "/home/user/repos/my-app"
username = "youruser"

[[project]]
name = "OSS Project"
source = "github"
project = "org/oss-project"
local_path = "/home/user/repos/oss-project"
username = "youruser"

Single-project config (backwards compatible)

[gitlab]
host = "gitlab.example.com"
token = "glpat-your-token-here"
project = "team/my-app"
local_path = "/home/user/repos/my-app"
username = "youruser"

Agent-only config (no forge)

pertmux supports two coding agents: opencode and Claude Code. Enable one or both in your config.

opencode must be started with --port 0 so pertmux can query its local HTTP server for session status:

refresh_interval = 2

[agent.opencode]
# db_path = "~/.local/share/opencode/opencode.db"

Claude Code requires no special flags — pertmux reads its JSONL transcript files automatically:

refresh_interval = 2

[agent.claude_code]

Config reference

[gitlab]

[github]

[[project]]

[agent.opencode]

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

[agent.claude_code]

Including this section enables the Claude Code agent. Omit or comment it out to disable. Claude Code requires no special startup flags — pertmux reads its JSONL transcript files from ~/.claude/ automatically.

[[agent_action]]

Define custom agent actions sent to coding agent instances. When present, replaces the built-in defaults. Omit to use the two default actions (rebase, pipeline fix).

[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.

Keybindings

Navigation

Actions (configurable)

Action keys can be remapped via the [keybindings] section in your config file. Defaults shown below.

Pipeline Visualization

The pipeline job status dots in the MR detail panel are inspired by glim. Each CI/CD job is rendered as a colored dot for a compact at-a-glance view of pipeline health, grouped by stage.