Querying and filtering

Use an exact target when you know its name, or filter a listing when you need to inspect several objects. A session named work and one named worker should not become interchangeable targets.

Require exactly one match¶

Prefix a session target with = to require an exact name. has-session reports whether it exists; it does not return a pane. This script selects panes in work and rejects both zero matches and multiple matches before using an ID.

Save the complete script as query.sh. It requires tmux 3.2a or newer and a POSIX shell. It creates and cleans up its own server.

#!/bin/sh
set -eu
directory=$(mktemp -d "${TMPDIR:-/tmp}/libtmux-guide.XXXXXX")
socket="$directory/tmux.sock"

cleanup() {
    status=$?
    trap - 0 HUP INT TERM
    if [ -S "$socket" ] && ! tmux -S "$socket" kill-server; then
        printf 'Cannot stop tmux; kept %s\n' "$directory" >&2
        exit 1
    fi
    rm -rf "$directory" || status=$?
    exit "$status"
}
trap cleanup 0
trap 'exit 1' HUP INT TERM

tmux -S "$socket" -f /dev/null new-session -d -s work 'cat'
tmux -S "$socket" new-session -d -s worker 'cat'
tmux -S "$socket" has-session -t '=work'

panes=$(tmux -S "$socket" list-panes -a \
    -f '#{==:#{session_name},work}' -F '#{pane_id}')
# Pane IDs contain no whitespace; split the rows to count matches.
# shellcheck disable=SC2086
set -- $panes
if [ "$#" -ne 1 ]; then
    printf 'Expected one work pane, found %s.\n' "$#" >&2
    exit 1
fi
tmux -S "$socket" display-message -p -t "$1" '#{session_name}'

Run the saved script:

$ sh query.sh

The output is work. The worker session remains outside the result. Targeting the returned pane ID avoids repeating name matching when the next command runs. An object can still disappear between commands; keep errors visible.

Declarative filters¶

list-panes -a searches every session. -f evaluates a tmux format as a boolean for each pane; here #{==:#{session_name},work} keeps only exact session-name matches. -F chooses what each returned row contains. Using only #{pane_id} keeps the result easy to pass to another tmux command.

Case-insensitive matching¶

Choose case handling explicitly when a name may vary in capitalization. tmux’s m format operator supports an i modifier for case-insensitive matching. Keep the ordinary == comparison when exact case is part of your contract. Filtering and queries explains the query model.

Push the filter into tmux, or read once and filter locally¶

A tmux-side filter reduces returned rows. Capturing a listing once and filtering it in your program is useful when several decisions should use the same read. Neither approach reserves the objects. Unknown format names expand to empty values; check an unexpectedly empty result before assuming nothing exists.

Use a language library¶

The port dropdown opens the language’s query guide. These complete programs connect to an existing server, find exactly the work session and report its absence:

Python · TypeScript · Go · Rust · Java · Kotlin · Scala · C# · F# · C++ · Swift · Ruby · Lua

tmux reference¶

See has-session, list-panes, and the target syntax. The version selector shows the flags supported by your installed tmux release.

The tmux manual documents these commands and their flags.