Navigate tmux command history like RPG waypoints: jump back to a command and its output, fill it into the prompt, or build your own workflow. tmux-waypoints is extensible through actions, hooks, and display adapters written in any language with an executable entrypoint.

Requirements

• tmux 3.4 or later (3.6b recommended)
• zsh 5.3 or later

The built-in popup display adapter requires fzf. fzf is not required by the core: set @waypoints-display to another display adapter to use tmux-waypoints without fzf.

Installation

Installation with Tmux Plugin Manager (recommended)

Install Tmux Plugin Manager, then add tmux-waypoints to the plugin list in .tmux.conf:

set -g @plugin '0xJohnnyboy/tmux-waypoints'

Keep TPM's initialization line at the bottom of .tmux.conf, after the plugin list and any @waypoints-* options:

run '~/.tmux/plugins/tpm/tpm'

Add the zsh adapter to .zshrc after your prompt setup:

source "${TMUX_PLUGIN_MANAGER_PATH:-$HOME/.tmux/plugins}/tmux-waypoints/shells/zsh.tmux-waypoints.zsh"

Press prefix + I inside tmux to fetch and load the plugin, then start a new zsh session.

Manual installation

The assisted installer clones tmux-waypoints, checks git, tmux and zsh, and offers to add clearly marked blocks to .tmux.conf and .zshrc. Existing files are backed up before they are changed. It never installs system packages or runs sudo.

For the shortest setup, run:

curl -fsSL https://raw.githubusercontent.com/0xJohnnyboy/tmux-waypoints/main/scripts/manual-install.sh | sh

This command downloads and executes the installer from the current main branch. To inspect it first and control the checkout location, clone the repository yourself and run the same assistant locally:

waypoints_dir="${XDG_DATA_HOME:-$HOME/.local/share}/tmux-waypoints"
git clone https://github.com/0xJohnnyboy/tmux-waypoints.git "$waypoints_dir"
sh "$waypoints_dir/scripts/manual-install.sh"

The bootstrap installs the checkout in ${XDG_DATA_HOME:-$HOME/.local/share}/tmux-waypoints by default. Preview without changing or cloning anything:

curl -fsSL https://raw.githubusercontent.com/0xJohnnyboy/tmux-waypoints/main/scripts/manual-install.sh | sh -s -- --dry-run

Use --yes for an explicit non-interactive installation. Custom locations are available through --install-dir, --tmux-conf, and --zshrc; run the installer with --help for details.

If tmux is running, the assistant reloads .tmux.conf. Otherwise it prints the exact reload command. In both cases, start a new zsh session afterwards. Put custom @waypoints-* options before the managed tmux-waypoints block.

To roll back, restore the reported *.tmux-waypoints.bak.<timestamp> files, or remove the blocks between # >>> tmux-waypoints >>> and # <<< tmux-waypoints <<<. The checkout is left untouched.

First use

Press prefix + W in a zsh pane to open the picker. Type to filter using fzf; Enter runs jump, . fills the current prompt without executing, and X clears this pane's recorded waypoints only. Escape closes the picker.

The built-in popup display uses fzf. Install it with your package manager, for example sudo apt install fzf on Debian/Ubuntu or brew install fzf on macOS. tmux-waypoints does not install or download fzf automatically. A custom display adapter may use any UI and does not need fzf.

Options

set -g @waypoints-key W                 # Binding installed by the plugin.
set -g @waypoints-show-success 1        # Set 0 to hide successful commands.
set -g @waypoints-show-failure 1        # Set 0 to hide non-zero exits.
set -g @waypoints-limit 0               # 0 means no display limit.
set -g @waypoints-exclude '^(pass|secret) '
set -g @waypoints-log-level error       # off, error, info, debug
set -g @waypoints-clear-resets on        # Reset after `clear` commands.
set -g @waypoints-display popup          # Built-in fzf display adapter.
set -g @waypoints-fzf-bindings 'ctrl-f:fill'

@waypoints-exclude is an extended regular expression. Compose several rules with |, for example '(token|password|^ssh )'. Excluded commands are never stored, but their position is counted so later visible commands still navigate correctly.

Waypoints are local to a pane and are intentionally not restored by tmux-resurrect or tmux-continuum. Data is scoped to the live tmux server, window and pane, below $XDG_RUNTIME_DIR/tmux-waypoints-$UID (or /tmp when unavailable). Killing a pane or window removes its waypoint data. It is stored in clear text; treat it like shell history.

@waypoints-fzf-bindings is a comma-separated list of key:action mappings. Each action must be discoverable through the regular action extension API. Built-in keys (Enter, ., and X) cannot be replaced. Invalid mappings are ignored and logged.

Current scope

zsh is supported. The storage and navigation contract is shell-neutral so a bash adapter can be added without changing the picker or journal format.

Extensions

Built-ins live in actions/, hooks/, and displays/. User extensions live under $XDG_CONFIG_HOME/tmux-waypoints/ (or ~/.config/tmux-waypoints/) in the same directories. Every extension has an adjacent TOML manifest and an executable entrypoint. The entrypoint's shebang selects its runtime; Go hooks should be compiled binaries.

Extensions receive a versioned JSON context on stdin, write a JSON response on stdout, and write diagnostics on stderr. Schemas are in schemas/. Hooks with priority 10 execute before priority 100. Use bin/tmux-waypoints doctor to diagnose discovered entrypoints; completions and man/tmux-waypoints.1 are distributed for optional installation.

The popup display is only the built-in fzf adapter. Select another display with @waypoints-display to replace fzf entirely; actions and their hooks stay owned by the core.

Memory benchmark

Run tools/benchmark-memory.sh 200 to compare an empty tmux server and one with the zsh adapter under the same 200-command workload. The TSV output contains server RSS, runtime data size, waypoint count, and detected auxiliary processes. The script uses temporary servers and removes them afterwards.

License

tmux-waypoints is licensed under the GNU Affero General Public License v3.0.