Tmux

📟 Modern Tmux: The Terminal as a Tiling WM

A high-performance tmux configuration optimized for project isolation, AI agent workflows, and keyboard-driven speed.

This setup is heavily inspired by Raine Virta’s work on Modern Tmux and the workmux tool.

🧠 Core Philosophy: Sovereign Isolation

In a modern development environment—especially when using AI Agents (like Aider or Claude Engineer)—the biggest bottleneck is context switching and file-system conflicts.

Our tmux setup solves this by treating every task as a disposable, isolated worktree.

🛠️ Workmux: Parallel Tasking (Prefix + w)

Instead of switching branches in a single directory (which breaks builds and confuses AI agents), we use Workmux.

• Action: Press Prefix + w.
• Workflow:
  1. Pick an existing branch or create a new one.
  2. Workmux automatically creates a physical Git Worktree in your project’s .worktrees/ directory.
  3. It opens a new tmux window inside that isolated folder.
• Benefit: You can run an AI agent in Window 1 (fixing a bug) while you manually refactor code in Window 2. They will never touch each other’s files.

🖥️ The Singleton Terminal Workflow (open-term)

To maintain a clean and focused workspace, we use the hey .open-term orchestrator. It ensures that you only have one terminal window per tmux session.

How it Works

When you trigger a terminal launch (via keybind or Rofi):

1. Window Check: It queries the Window Manager (Hyprland, Niri, or BSPWM) for an existing window with the target Class/App-ID (defaulting to workmux).
2. Intelligent Focus:
   • If the window exists: It instantly focuses it, even if it’s on a different workspace or monitor.
   • If not: It launches a new terminal instance.
3. Session Persistence: It uses tmux new-session -A -s <name> to ensure you always attach to your existing session if it’s running in the background.

Command-Specific Windows

If you run a specialized command via the terminal (e.g., hey .open-term -- btm), the system automatically creates a dedicated session (e.g., workmux-btm). Running the command again will focus that existing window rather than opening a duplicate.

🚀 Rofi Integration

The terminal workflow is deeply integrated with Rofi for quick access.

1. Terminal Menu (hey @rofi termmenu)

An interactive menu to launch your preferred terminal emulator (Foot, Ghostty, Alacritty, etc.).

• Behavior: Picking a terminal follows the singleton logic. It will focus your existing workmux window first, or launch the new emulator if none exists.

2. Workspace Picker (hey @rofi tmux)

A quick switcher for your named tmux sessions (e.g., ohmeta, research, blog).

• Behavior: Selecting a workspace will instantly focus its window if open, or launch a new terminal and attach to that specific tmux session.

3. File Explorer (hey @rofi filemenu)

When browsing directories, you can press a key (configured via -file-browser-cmd) to open the current folder in a terminal.

• Behavior: This uses hey .open-term cd <path>, which bypasses the singleton focus logic to ensure a fresh window opens exactly where you need it.

𐄂 Interactive Popup Menus

We use the tmux display-popup command to run fzf-powered tools without losing your place in the current terminal.

📂 File Picker (Prefix + f)

Providing context to an AI agent often requires typing long paths.

• Action: Press Prefix + f.
• Workflow: A popup appears listing all files in the current repo (via fd). Select one with fzf.
• Result: The absolute path is pasted directly into your prompt.

🔀 Session Switcher (Prefix + S or /)

Instead of a random list of session IDs, our switcher uses a Workspace Registry:

• Standard Slots: Predefined workspaces like workmux, ohmeta, and bioinfo are always at the top.
• Auto-Creation: If you select a workspace that isn’t running, the script instantly initializes it and switches you there.
• Dynamic List: Any other active sessions are listed below the standard slots.

⚡ High-Speed Navigation

We have bypassed the “Prefix delay” for common movements, making tmux feel like a native Tiling Window Manager.

Note: Alt navigation is a “No-Prefix” bridge—you do not need to press Ctrl-c first.

🔧 Technical Integration

This workflow is powered by the HeyOS Toolchain:

• Janet Scripts: Located in config/tmux/bin/. These scripts (filepicker.janet, sessionmenu.janet) are called via hey @tmux <name>.
• Workmux Wrapper: The Prefix + w bind triggers a custom zsh wrapper (config/tmux/bin/workmux.zsh) that uses fzf to let you interactively select or type a branch name before handing full control over to the official, Rust-based workmux binary.
• Nix Integration: Dependencies like workmux, fzf, and fd are declaratively managed in modules/shell/tmux.nix and modules/dev/agents.nix.
• Terminal Bridge: Ghostty and Alacritty are configured to pass through Alt-keys directly to tmux for zero-latency switching.

🔗 References

• Raine Virta: My Tmux Setup
• Workmux Official Documentation