Alfred Tmux Sessions

A powerful Alfred workflow for complete tmux session management with multi-terminal support (iTerm2, Ghostty, Terminal.app). List, create, attach, detach, and delete sessions with rich status info via the tmux keyword.

Setup

Requirements

• macOS 10.14+
• Alfred 4.0+ with Powerpack
• tmux 3.2+ - Install via brew install tmux
• At least one supported terminal:
  • iTerm2 - Install via brew install --cask iterm2
  • Ghostty - Install via brew install --cask ghostty
  • Terminal.app (built-in fallback)

Download

1. Download the latest Tmux Sessions Alfred Workflow
2. Double-click the file to install in Alfred
3. Grant necessary permissions when prompted

Verification

Test the workflow by typing tmux in Alfred. If you see "tmux not found", install tmux with:

brew install tmux

Usage

List and search tmux sessions via the tmux keyword. Results are intelligently sorted (attached sessions first, then by recent activity) and can be filtered instantly by typing any part of a session name. Each session displays:

• 🟢 Attached or ⚪ Detached status
• Window count and creation time
• Last activity timestamp

Actions

• ⏎ Attach to session - Opens in focused terminal window or creates new window
• ⇧⏎ Open linked session - Creates a linked session (e.g., session@2) with independent window navigation - perfect for viewing different windows in separate terminal windows
• ⌘⏎ Delete session - Permanently removes the session
• ⌃⏎ Detach from session - Disconnects clients (attached sessions only)

Create New Sessions

Type tmux followed by a new session name to create it instantly:

• ⏎ Create and attach - Creates the session and opens in your configured terminal

The workflow also provides:

• Input validation to prevent invalid session names with helpful error messages
• Rich notifications with success and error feedback for all operations

Linked Sessions

Linked sessions (also called grouped sessions) share the same windows and content as the base session but allow independent window navigation. This is perfect for:

• Multi-monitor setups - View different windows of the same session on different monitors
• Split workflows - Keep Claude Code visible in one window while running commands in another
• Collaborative work - Multiple views of the same session without forcing synchronized navigation

Example:

• Base session: corpit-lambdas-feature
• Linked sessions: corpit-lambdas-feature@2, corpit-lambdas-feature@3

Each linked session can navigate to different windows independently, but all changes (new windows, pane content, etc.) are shared across all linked sessions.

Configuration

Terminal Selection

The workflow automatically detects your preferred terminal, but you can manually configure it:

1. Access Configuration: Right-click the workflow in Alfred Preferences → "Configure Workflow..."
2. Terminal Application: Choose from the dropdown:
   • Auto (Detect Best Available) - Automatically selects iTerm2 → Ghostty → Terminal.app
   • iTerm - Force iTerm2 usage
   • Ghostty - Force Ghostty usage
   • Terminal - Use built-in Terminal.app

Ghostty Setup

If using Ghostty, you'll need to grant both Accessibility and Automation permissions:

1. Go to System Settings → Privacy & Security → Accessibility
2. Add Alfred to the allowed applications
3. Go to System Settings → Privacy & Security → Automation
4. Allow Alfred to control Ghostty
5. This enables the workflow to control Ghostty via GUI scripting

Additional Options

• Change keyword: Alfred Preferences → Workflows → Tmux Sessions → Script Filter
• View logs: Check ~/Library/Logs/Alfred/alfred-tmux-sessions.log for debugging

Troubleshooting

Common Issues

"tmux not found"

• Install tmux: brew install tmux
• Verify installation: tmux --version

"Configured terminal not found"

• Verify your selected terminal is installed
• Try switching to "Auto" detection in workflow configuration

Ghostty not responding

• Ensure Accessibility permissions are granted for Alfred
• Check System Settings → Privacy & Security → Accessibility

"Session ended very soon after starting"

• Check your terminal's default profile settings
• Verify tmux is in your PATH: run which tmux and echo $PATH
• For GUI applications, ensure PATH is set in ~/.zprofile (zsh) or ~/.bash_profile (bash)

"New sessions use the wrong shell"

• The workflow auto-detects your terminal's running shell, but on some macOS login-shell setups the exact executable path can't be recovered reliably
• If your terminal uses a custom shell binary (e.g., Homebrew bash or fish), set the default_shell workflow variable to the full path (e.g., /opt/homebrew/bin/bash)
• Alternatively, add set -g default-shell /path/to/your/shell to your ~/.tmux.conf

Sessions not showing

• Verify tmux sessions exist: tmux list-sessions
• Check the debug log at ~/Library/Logs/Alfred/alfred-tmux-sessions.log

Limitations

• Ghostty requires macOS Accessibility permissions for GUI scripting
• Session names cannot contain spaces, dots, colons, quotes, or backslashes (max 100 characters)
• Detach action only works on sessions with active clients

Development

The workflow consists of:

• Python script (src/tmux-sessions.py) - Session listing and filtering
• AppleScript (src/tmux-action.scpt) - Session operations and multi-terminal integration

Building from Source

git clone https://github.com/JasonSatti/alfred-tmux-sessions.git
cd alfred-tmux-sessions

# Import workflow files manually into Alfred
# Or modify and export your own .alfredworkflow

License

MIT License - see LICENSE for details.

---

If this workflow saves you time, consider ⭐ starring the repo to help others discover it!