zmx-picker

July 24, 2026 · View on GitHub

A fuzzy finder for zmx sessions and repositories, provided as the zp command.

zp presents your running zmx sessions in an fzf picker with log and scrollback previews. When given root directories to search, it also lists any git or jj repositories beneath them. Selecting a session attaches to it; selecting a repository starts a numbered session inside it.

Requirements

zmx and fzf (>= 0.51)
optional: git and/or jj for repository previews
optional: fd for faster repository scans

Installation

Homebrew

brew install EarthmanMuons/tap/zmx-picker

This installs the zp command along with zmx and fzf.

Manual

Copy the zp script somewhere on your PATH.

Usage

usage: zp [root ...]

zmx-picker - lists zmx sessions, plus repos under any roots
given as arguments or $ZP_ROOT (colon-separated)

options: -h/--help, -V/--version

For example, to always pick from repositories under ~/src, set:

Bash:

export ZP_ROOT="$HOME/src"

fish:

set -gx ZP_ROOT $HOME/src

Tip

Bind zp to a key for quick access:

# bind Ctrl-\ to zp when not inside a zmx session;
# inside zmx, Ctrl-\ detaches the current session
if not set -q ZMX_SESSION
    bind ctrl-\\ 'zp; commandline -f execute'
end

Inside the picker:

Key	Action
`Enter`	Attach the selection, or create a session named after an unmatched query
`Tab`	Mark or unmark a session
`Ctrl-N`	Create a session named after the query, even when a candidate is highlighted
`Ctrl-X`	Kill the marked sessions, or the highlighted one when none are marked
`Esc`	Cancel

Sessions created from a repository are named <repo>.<n> with the next free number and start in the repository's directory; sessions created from a query start in the current directory.

Any zmx session labels (zmx set <name> key=value) are shown alongside each session and are fuzzy-searchable, so typing key=value narrows the picker to the sessions that carry that label.

License

zmx-picker is released under the Zero Clause BSD License (SPDX: 0BSD).