Modes
Modes are the core concept in tmux-dispatch. Each mode gives you a different way to interact with your tmux environment — finding files, searching content, managing sessions, and more — all from a single popup that stays open as you work.
Files is the home mode. You start here every time you open the popup. From files, type a prefix character to jump to any other mode. Backspace on an empty query returns you home. This creates a natural hub-and-spoke pattern: start at files, jump to what you need, come back when you’re done.
Mode Overview
| Mode | Prefix | Description | When to use it |
|---|---|---|---|
| File Finder | (home) | Fuzzy file search with bat preview, bookmarks, frecency ranking, git status indicators, and global marks sub-view (Ctrl+G) | You want to quickly open, preview, or manage any file in your project |
| Live Grep | > | Ripgrep reloads on every keystroke with line-highlighted preview | You need to find where a function is defined or search for a specific string |
| Git Status | ! | Stage/unstage files with Tab, colored status icons, inline diff preview | You want to review changes, stage files, or check what you’ve modified |
| Directories | # | Jump to directories via zoxide frecency or fd/find fallback | You need to cd into a project directory or recent folder |
| Sessions | @ | Switch, create, rename, or kill tmux sessions with window grid preview | You want to jump between projects or spin up a new workspace |
| Windows | (from sessions) | Browse windows within a session using 2D grid navigation with pane content preview | You want to see what’s running in each window before switching |
| Scrollback Search | $ | Search and copy from terminal scrollback with context preview | You want to grab a command, path, or output from your terminal history |
| Token Extraction | & | Extract URLs, file paths, git hashes, IPs, UUIDs from terminal scrollback | You want to quickly grab and act on structured data from terminal output |
| Custom Commands | : | Run user-defined commands from a configurable palette | You have custom scripts, tmux commands, or workflows you run frequently |
| Marks | Ctrl+G (from files) | Global bookmarks – sub-view of files showing all bookmarked files across all directories | You want to jump to a frequently-used file in a different project |
| Path | / | Browse files by absolute path from any directory | You know the full path to a file or want to browse outside your project |
| Panes | (coming in v1.1) | Browse and manage panes across all tmux sessions | You need to switch to, swap, or kill a pane in another session |
How Mode Switching Works
Mode switching uses prefix characters — special characters that, when typed as the first character in the query, switch you to a different mode:
- Type
>to switch to grep — the rest of your query becomes the search term (e.g.,>useStatesearches for “useState”) - Type
@to switch to sessions — filter sessions by name (e.g.,@apishows sessions containing “api”) - Type
!to switch to git status — see your uncommitted changes - Type
#to switch to directories — jump to a recent or nearby directory - Type
$to switch to scrollback search — find and copy text from your terminal history - Type
:to switch to custom commands — run commands from your personal palette - Type
&to switch to token extraction — extract and open URLs, file paths, hashes from terminal output - Type
~to switch to files from home directory — browse all files under$HOME - Type
/to switch to path mode — browse files by absolute path from any directory
In any sub-mode, press Backspace on an empty query to return to the file finder. This works like VSCode’s command palette — you never need to close and reopen the popup.
Windows mode is accessed from sessions mode by pressing Ctrl+W on a session, and returns to sessions with Backspace.
See Mode Switching for the full details on prefix-based navigation.