zsh-tmux

April 28, 2026 · View on GitHub

Automatic tmux window title management for Zsh — live updates as commands run.

Know at a glance what every pane is doing. zsh-tmux hooks into Zsh's precmd and preexec to keep your tmux window titles in sync — idle panes show zsh, running panes show the command name, and job references like fg resolve to the actual process.

Requirements

tmux (tmux)

macOS (Homebrew):

brew install tmux

Nix:

nix profile install nixpkgs#tmux

Installation

Using zinit

zinit load zsh-contrib/zsh-tmux

Using sheldon

[plugins.zsh-tmux]
github = "zsh-contrib/zsh-tmux"

Manual

git clone https://github.com/zsh-contrib/zsh-tmux.git ~/.zsh/plugins/zsh-tmux
source ~/.zsh/plugins/zsh-tmux/zsh-tmux.plugin.zsh

Behavior

State	Window Title
Idle at prompt	`zsh`
Running `vim file.txt`	`vim`
Running `npm run build`	`npm`
Long command name	Truncated with `...`

Titles are capped at 20 characters and have newlines stripped and percent signs escaped.

Outside tmux: the plugin falls back to OSC 0 (ESC ] 0 ; <title> BEL), the xterm-standard window-title sequence supported by Ghostty, Kitty, iTerm2, Apple Terminal, Alacritty, WezTerm, etc. — so non-tmux users get live window titles too.

On TERM=dumb / pipes / non-interactive shells: no escape is emitted.

Configuration

Conditional Loading

Only load when inside tmux:

if [[ -n "$TMUX" ]]; then
  zinit load zsh-contrib/zsh-tmux
fi

Disabling titles entirely

Set ZSH_TMUX_DISABLE_TITLE=1 before the plugin is sourced (or any time before update_title runs) to suppress all title updates — useful when another plugin or your prompt is already managing the window title.

export ZSH_TMUX_DISABLE_TITLE=1

Tmux Configuration

Ensure tmux is configured to display window titles:

# ~/.tmux.conf
set -g set-titles on
set -g set-titles-string "#W"

API Reference

`update_title <title>`

Sets the tmux window title with automatic truncation.

update_title "vim"
update_title "very-long-command-name"  # shows: "very-long-comman..."

Hook Functions

Registered automatically — do not call directly.

Hook	Trigger	Action
`_zsh_title__precmd`	Before each prompt	Sets title to `zsh`
`_zsh_title__preexec`	Before command execution	Sets title to command name

_zsh_title__preexec extracts the first word of the command and resolves job references (fg, %1, %+) to the actual command text.

The zsh-contrib Ecosystem

Repo	What it provides
zsh-aws	AWS credential management with aws-vault and tmux
zsh-eza	eza with Catppuccin and Rose Pine theming
zsh-fzf	fzf with Catppuccin and Rose Pine theming
zsh-op	1Password CLI with secure caching and SSH key management
zsh-tmux ← you are here	Automatic tmux window title management
zsh-vivid	vivid LS_COLORS generation with theme support