Omamux

Omamux is a local tmux session picker for the Omarchy Quattro bar. It brings flagship session picker from TermRover.sh to Omarchy.

Version 0.1.0 is intentionally local-only. Remote host support is planned after the local workflow is stable.

The demo shows session navigation, favorites, reordering, and inline session renaming.

• j/k: move the selection.
• f: toggle the selected session as a favorite.
• J/K (Shift+j/Shift+k): reorder a favorite.
• r: rename the selected session.
• R (Shift+r): refresh sessions.
• C (Shift+c): create a session.
• Right/Left: open session details or return to the session list.
• Enter: attach to the selection, focus its existing local window, or recreate a saved session that is not running.

• Lists local tmux sessions with window count, age, and attached client count.
• Opens an exact session in Omarchy's configured terminal.
• Focuses an existing local Hyprland terminal instead of opening a duplicate.
• Creates and immediately attaches to a named session.
• Renames an existing session while preserving its favorite position.
• Keeps ordered favorites, with drag and keyboard reordering.
• Preserves favorite sessions that no longer exist, shows them as Not running, and provides a one-click option to recreate them with the same name.
• Shows the windows and panes running inside each session.
• Supports mouse and keyboard navigation.
• Keeps keyboard selection in control until the pointer genuinely moves or clicks, including after a favorite reorder.
• Refreshes automatically without changing tmux configuration or global options.
• Inherits Quattro popup colors, borders, fonts, spacing, and theme changes.

• Omarchy Quattro
• tmux
• Bash
• jq
• GNU coreutils (timeout)

Omamux runs with your normal user permissions. It does not install packages or request elevated privileges.

omarchy plugin add https://github.com/ptgamr/omamux.git --enable

The manifest places Omamux in the right bar section by default. Move it if desired:

omarchy bar move io.github.ptgamr.omamux --section right

• Left-click the bar widget to open or close the session panel.
• Right-click the bar widget to refresh.
• Use j/k or the arrow keys to select a session, then press Enter to attach.
• Click ☆/★, or press f, to toggle a favorite.
• Drag a favorite row, or press Shift+j/Shift+k, to reorder it.
• Locally attached sessions show their Hyprland workspace as ws N.
• Press Right to inspect a session's window-and-pane tree and use j/k to select either level.
• Press Enter on a window or pane to focus that exact tmux target, then Left to go back.
• Click +, or press Shift+C, to create a session.
• Press r to rename the selected session, then Enter to confirm or Escape to cancel.
• Press Shift+R, use the refresh button in the panel header, or right-click the bar widget, to refresh.
• Press Escape to close.
• Missing favorites are labeled Not running; select one and press Enter or click + to recreate and attach to it.

New favorites are inserted at the top. Favorites for sessions that no longer exist remain visible in their saved order, where they can be reordered, removed, or recreated with the same name.

When a selected session is already attached in a local Hyprland terminal, Omamux switches to that window's workspace and focuses it. Remote-only attachments do not count as local windows. Selecting a different window or pane in a session with attached clients requires a second Enter because changing tmux's active target affects every client attached to that session.

Favorite order is stored at:

${XDG_STATE_HOME:-$HOME/.local/state}/omamux/favorites.json

Writes are atomic. If the file is malformed, Omamux reports the problem and preserves the file rather than overwriting it.

Validate the repository without installing it:

omarchy plugin validate .
qmllint -I "$OMARCHY_PATH/shell" BarWidget.qml Panel.qml
node tests/test-model.mjs
bash tests/test-omamux.sh

The backend test creates a unique temporary tmux socket and state directory. It does not inspect or mutate your normal tmux server.

For live development, copy the repository contents into:

~/.config/omarchy/plugins/io.github.ptgamr.omamux/

Then rescan and enable it:

omarchy-shell shell rescanPlugins
omarchy plugin enable io.github.ptgamr.omamux

QML changes in the user plugin directory reload automatically.

omarchy plugin remove io.github.ptgamr.omamux

Removing the plugin does not remove its favorites file.

Omamux does not edit .tmux.conf, Omarchy configuration, terminal configuration, tmux global/server options, colors, or theme synchronization. Session names are passed as command arguments rather than interpolated into shell command strings, and existing sessions are addressed with exact tmux targets.

State, Hyprland client data, and tmux client/session/pane data are captured with fixed byte ceilings before parsing. Omamux also limits row counts and retained field lengths; oversized input is rejected with a structured error instead of being forwarded to QML.

Subprocesses that only report success or failure, including a configured OMAMUX_TERMINAL_LAUNCHER, have their streams discarded so their output cannot reach or corrupt the JSON result.

The favorites file is read through a single time-bounded open. The descriptor is validated as a regular file and then read without a second pathname lookup, so the path cannot be swapped for a blocking special file or a substituted file between validation and the read.

See PLAN.md for the full local-first design and the later remote-host direction.