rolomux

A slick tmux session picker that sorts your sessions into color-coded groups to bring you terminal zen.

Your terminal is a workshop. As a woodworker, I've learned that a tidy workshop is easier to work and think in. Every tool needs a home, and should be put away when you're not using it. Rolomux helps you keep your terminal tidy, giving you a home for every tmux session, keeping your active projects front and center on your workbench, and helping you put things back on the shelf when you aren't using them.

brew install jeffdt/tap/rolomux

Then add a keybind to ~/.tmux.conf to pop it open:

bind s display-popup -E -B -w 84 -h 60% "exec rolomux"

Reload tmux and press prefix + s.

You can use other popup dimensions, but these work well to start. -h also accepts a fixed line count (e.g. -h 30) instead of a percentage.

1. Press prefix + s to open rolomux. All of your sessions start out in a group called INBOX.
2. Move a few sessions around with ⇧J and ⇧K.
3. Press g to raise the cursor to group altitude.
4. Press n to create a new group. Call it PROJECTS, then press Esc to return to the picker.
5. Move a session into PROJECTS with ⇧J and ⇧K.
6. Try creating a few more groups, reordering the groups themselves, and changing their colors.
7. Press d on a session to mark it dormant, then f to enter focus mode and watch it drop out of view. Press f again to bring it back.

New sessions arrive in INBOX. Over time, you sort, group, and reorder them until your workspace feels the way you want it to.

• Create your groups. Press g to raise the cursor to group altitude, where you can create, rename and color code your groups while your sessions stay visible below.
• Sort your sessions. Move your sessions between groups with ⇧J/⇧K. Once sorted, they stay there, in that order. New sessions collect in an inbox until you're ready to sort them. Groups and their ordering persist across tmux restarts, and they stick around until you delete them.
• Dim sessions, then focus past them. Press d to mark a session dormant; it stays in place but renders in a dimmed state to indicate that you're not actively working with it. Press f to enter focus mode, hiding dormant sessions and any group left with nothing visible in it; press f again to show everything. Dormant sessions are still fully usable when shown, and focus mode helps you understand your workspace at a glance. d also works on an individual window within an expanded session -- its own dormant flag is independent of the session's, shown with strikethrough, and hidden by focus mode unless it's the session's active window (which always stays visible, the same exemption that keeps your attached session visible).
• Expandable trees. Each session can be expanded to peek at the list of windows inside it or jump straight to a specific window.
• Lightweight. One tmux query per launch. No hooks or background processes keeping track of your sessions while you work.
• Fuzzy search built in. Press / to filter sessions by name. If this is your preferred way of working, tweak the settings to always launch in search mode.
• Tune the colors. Press , to open Settings and tune the color of the application border, palette used for group headers, and more. Uses your terminal's ANSI colors to ensure it harmonizes with your existing terminal themes.

Note: rolomux depends on (and promotes) good tmux hygiene. Get in the habit of naming your sessions and windows so you can make sense of them later. You can reinforce this habit with your binds for creating sessions and windows, immediately prompting you for the name at creation time:

bind c new-window -c "#{pane_current_path}" \; command-prompt -I "" "rename-window '%%'"
bind C new-session \; command-prompt -I "" "rename-session '%%'" \; command-prompt -I "" "rename-window '%%'"

M- is Meta (Option on macOS). Your terminal must send Option as Meta: in Ghostty set macos-option-as-alt = true (iTerm2: "Left Option key → Esc+"; Terminal.app: "Use Option as Meta key"). On Linux it is automatic.

When a session is at the top of its group, ⇧K jumps it up to the group above it; when it's at the bottom, ⇧J drops it into the group below it. The same idea applies one level down: expand a session and put the cursor on a window, and ⇧J/⇧K reorders that window within its session, crossing into the neighboring session's last/first slot at the edge. Moving a session's very last window would destroy that session, so rolomux only ever does that automatically when it's provably safe (no attached client, or one that tmux will gracefully switch elsewhere via detach-on-destroy off); otherwise it asks you to press the same key again to confirm, or -- if confirming would eject someone's attached client -- quietly leaves a placeholder window behind instead of destroying the session at all.

Every ⇧J/⇧K press also flashes a brief ▲/▼ next to whichever row(s) just moved (sessions, windows, and groups alike) -- right before a session's metadata, or after a window's or group's name -- fading out after about a second.

Press g to raise the cursor to group altitude: the cursor moves up onto group headers while your sessions stay visible underneath, dimmed to show they're not the current focus. Group structure (create, rename, recolor, reorder, delete) all happen in place, with your sessions still on screen for reference. g or Esc descends back to exactly the session or window you were on.

As you create groups, they'll be assigned a color from your terminal theme (cyan, green, yellow, magenta, blue, red, white); new groups rotate through them, c flips a group's color, and empty groups show grayed out until you fill them.

The inbox can be renamed and recolored like any other group, but it always stays last and can't be reordered or deleted.

You don't have to raise to group altitude just to add a group: at session altitude, ⇧N names a new empty group and drops it in above whichever session the cursor is on, without leaving the session list or touching that session's membership.

Press n at session altitude to create a brand new tmux session, or ⇧N at group altitude to create one directly inside the selected group. Either way you're prompted first for a session name, then optionally for a window name (leave it blank and press ↵ to skip and let tmux name it), and rolomux switches you straight to the new session once it's created.

Press / to enter search mode. Type any part of a session name; results are ranked best-match-first, with the top result auto-selected as you type. Enter switches to the highlighted session or window; Esc returns to command mode with the cursor left on the same match. Move within results with ↑/↓ (or Ctrl-n/Ctrl-p, Ctrl-j/Ctrl-k), wrapping between the first and last match. Backspace deletes the last character, Ctrl-W (or Option/Alt + Backspace) deletes the last word, and Ctrl-U clears the query. → (or Ctrl-L) expands the highlighted session's window tree and ← (or Ctrl-H) collapses it -- h/l themselves still just type into the query, since search never wants to steal an ordinary filter character.

While searching, section headers and jump numbers (sessions 1-20) are still hidden, but the tree otherwise behaves like command mode: expand a session to select and switch to one of its windows directly. If focus mode is on, search results exclude dormant sessions, and the footer shows how many are currently hidden.

Press d to mark the selected session dormant. It will render in a dimmed state as a visual cue of your paused work. Dormant sessions are still fully usable, and by default they also get assigned jump numbers. In Settings, change Number dormant sessions to No if you want dormant sessions to be skipped when jump numbers are assigned.

Once you have a few sessions marked dormant, you can press f to enter focus mode. In focus mode, both dormant sessions and empty groups disappear from view altogether. This is a powerful tool when you cannot afford distractions luring you away from your priorities. You will see a small reminder like 8 sessions hidden while focus mode is active.

Dormant sessions and focus mode persist across popups until turned off. Press f again to exit focus mode and everything will be restored exactly as it was. Press d again on a dormant session to mark it active again. Ctrl-d wakes up the selected session and every one of its windows in one press, and ⇧D is the nuclear option: it clears every dormant flag in the picker at once, instantly and with no confirmation.

Think of this as one more tool in your kit to keep your workbench clear and your focus intact.

Press , to open Settings, a full-screen view of picker-wide preferences, grouped into three colored sections. A description of the currently selected setting is always shown at the bottom. Each row shows a jump number in its gutter; pressing it jumps straight to that row and flips it, the same as moving there with j/k and pressing Enter -- handy for a setting you flip on and off often, like Remember expanded sessions.

Behavior

• Default mode. Whether the picker opens in Command mode or straight into Search.
• Number dormant sessions. Whether visible dormant sessions are included in jump numbering (sessions 1-20).
• Remember expanded sessions. Off by default (every popup starts fully collapsed). When on, expanding or collapsing a session's window tree (l/h/z) persists across popups, so the sessions you're actively jumping between stay expanded.
• Clear dormant on attach. Off by default. When on, attaching to a dormant session automatically clears its dormant flag, so you don't have to remember to press d yourself.
• Start in focus mode. Whether the picker starts in focus mode: Remember the last state (default), Always start in it, or Never start in it, regardless of what was last saved.
• Session metadata. Whether the row's trailing timestamp shows time since last activity (Recency, default), time since the session was created (Age), or is omitted entirely (Hidden).
• Show shortcuts. Whether the footer's key-shortcut legend is always visible (On, default), or hidden entirely (Off) -- press ? any time for the full shortcut list regardless of this setting.

Colors

• Attached session color. The color used to highlight the session your tmux client is currently attached to -- both its bolded name and a dot next to its jump number, mirroring the active window dot: a fixed Static color (default), or the session's own Group color.
• Active window color. Color of the ● marking a session's active window: a fixed Static color, or the session's own Group color.
• Border color. How rolomux's own border frame color is chosen: always use one Static color (default), Rotate through the border palette each time the popup opens, or pick a Random one each time.
• Border palette. Which of the 16 colors from your terminal theme are in the rotation for the border. Dims while Border color is Static, since the palette has no effect in that mode.
• New group color. How a newly created group picks its header color: Rotate through the palette in order, pick a Random color each time, or always use one Static color.
• Group palette. Which of the 16 colors from your terminal theme are in the rotation for new group headers. Dims while New group color is Static, for the same reason.
• Shortcut highlight color. The color used to highlight keys in the shortcut legend.

Appearance

• Inbox icon. The glyph shown before the inbox group's header. Cycle through a curated set with h/l.
• Caret style. The glyph used for the inline text caret when renaming, creating, or searching: a thin bar (default), an underline, or a solid block.
• Caret blink. Off by default (the caret stays solid). When on, the caret blinks.

Groups, session state, and settings persist to ~/.config/rolomux/config.toml. You normally don't edit this by hand; rolomux updates it automatically as you work.

Note: rolomux tracks each session by its tmux session id in this file, so renaming a session won't lose any of its rolomux state.

Agent-driven development has stretched our expectations on parallelism/multitasking to the extreme, and the biggest challenge is now context switching and staying organized. And while there are brand new tools popping up every day to launch and manage agents, tmux is an extremely mature, stable, and full-featured app that solved parallelism decades ago. It just lacks a few key qualities for keeping things organized. It isn't going to become vaporware, it's not going to have weird bugs that nobody catches because the userbase is too small, and its APIs are stable and easy for an agent to manipulate. It makes more sense to solve that organization gap than to throw it away and build some new tool altogether.

I want this tool to be fun to use, nice to look at, unobtrusive, and low-commitment. It places a high value on aesthetics but remembers it is a productivity tool first and foremost. It doesn't hook into your tmux session and watch for sessions being created or destroyed; it relies on live data available at the time it's invoked. It stores everything in a simple TOML file you could hand-edit if you desire, but should never have to. It's minimalist and clean in presentation and prefers to spend its complexity on customization. As a tool intended to be used all day every day, it should aim for zero friction. If a workflow takes two keystrokes instead of one, there would ideally be a setting that makes it one keystroke, for the people that plan to invoke that workflow every time they launch it. It favors your existing terminal palette over complete color customization to ensure it always feels like a "native" tool and not something bolted on later. Any new features must make the tool easier or more fun to use. Bloat is an enemy that must be actively kept at bay.

cargo build
cargo test
cargo run

This repo also ships two Claude Code skills for working on it visually: mockup, for comparing ANSI mockups of a design change before implementing it, and live-preview, for popping the freshly built binary open in a real tmux window once a feature is done. Both come from the tui-utils plugin:

/plugin marketplace add jeffdt/tui-utils
/plugin install tui-utils@tui-utils

This project was fully vibe coded. Use at your own risk.

rolomux is designed and tested for one tmux client attached to one session at a time. Running multiple terminals attached to different sessions simultaneously may or may not work; it isn't a tested or supported scenario.

MIT