A thin Starship adapter for tmux that renders beautiful, customizable status bars.

Use the full power of Starship to style your tmux status bar, with automatic access to tmux session, window, pane, and client information as environment variables.

• Full Starship compatibility — Use any Starship module, prompt, or theme in your tmux status bar.
• Rich tmux context — Session, window, pane, and client variables are automatically injected as TMUX_* environment variables.
• Per-side configuration — Separate Starship configs for status-left, status-right, and window-status (center).
• Prefix highlighting — Style your status bar differently when the tmux prefix key is active.
• Zero boilerplate — No wrapper scripts or complex tmux format strings required.

• tmux 3.0+
• Starship installed on your system
• Rust (if installing from source or crates.io)

cargo install tmuxship

cp examples/starship.toml ~/.tmux/starship.toml
cp examples/.right.toml   ~/.tmux/.right.toml
cp examples/.center.toml  ~/.tmux/.center.toml

Add to ~/.tmux.conf:

setenv -g TMUX_SHIP_LEFT_CONFIG   "$HOME/.tmux/starship.toml"
setenv -g TMUX_SHIP_RIGHT_CONFIG  "$HOME/.tmux/.right.toml"
setenv -g TMUX_SHIP_CENTER_CONFIG "$HOME/.tmux/.center.toml"

run-shell 'tmuxship apply'

tmux source ~/.tmux.conf

The recommended way to use tmuxship is tmuxship apply, which runs once at startup and converts your Starship TOML styles into native tmux status-left, status-right, and window-status options. This is fast, flicker-free, and requires no background processes.

For segments that need live data (battery, git status, frequently updating clocks), you can fall back to runtime rendering with #(tmuxship <side>). This runs every status-interval, injects TMUX_* env vars, calls Starship, and converts ANSI colors to tmux format strings.

You can mix both modes: use tmuxship apply for the frame, and override a single side with runtime rendering when needed.

tmuxship resolves Starship config files for each side (left, right, center) in the following order:

1. --config flag
2. TMUX_SHIP_<SIDE>_CONFIG environment variable (e.g. TMUX_SHIP_LEFT_CONFIG)
3. STARSHIP_CONFIG
4. $XDG_CONFIG_HOME/tmux/.<side>.toml
5. $XDG_CONFIG_HOME/tmux/starship.toml
6. $XDG_CONFIG_HOME/starship/.<side>.toml
7. $XDG_CONFIG_HOME/starship/starship.toml
8. $HOME/.config/tmux/.<side>.toml
9. $HOME/.config/tmux/starship.toml
10. $HOME/.tmux/.<side>.toml
11. $HOME/.tmux/starship.toml
12. $HOME/.config/starship/.<side>.toml
13. $HOME/.config/starship/starship.toml

set -g status on
set -g status-left-length 100
set -g status-right-length 200
set -g status-justify centre
set -g focus-events on

# Config paths for each status segment
setenv -g TMUX_SHIP_LEFT_CONFIG   "$HOME/.tmux/starship.toml"
setenv -g TMUX_SHIP_RIGHT_CONFIG  "$HOME/.tmux/.right.toml"
setenv -g TMUX_SHIP_CENTER_CONFIG "$HOME/.tmux/.center.toml"
setenv -g TMUX_SHIP_WINDOW_SEPARATOR " • "

# Generate status-left, status-right, and window-status options from Starship configs.
# Styles come from Starship TOML; tmux-native format strings (#S, #I, #W) render the values.
run-shell 'tmuxship apply'

# Refresh the status bar on relevant tmux events
set-hook -g client-session-changed 'refresh-client -S'
set-hook -g client-attached        'refresh-client -S'
set-hook -g pane-focus-in          'refresh-client -S'

set -g window-status-style "bg=default,fg=default"

# Default refresh interval (1 minute is plenty for static styling)
set -g status-interval 60

Key points:

• Config paths are set once with setenv -g and picked up automatically by tmuxship.
• tmuxship apply generates tmux options from Starship custom module styles, keeping color definitions in TOML.
• Runtime #(tmuxship right) still injects TMUX_* environment variables for shell-driven modules.
• Keep tmuxship on your PATH, or use an absolute path in your tmux config.

Some terminals or older tmux versions skip certain hooks. If your status bar feels stale on focus changes, uncomment these:

# Refresh on focus transitions
# bind-key -n FocusIn  refresh-client -S
# bind-key -n FocusOut refresh-client -S

# Additional hooks (uncomment if needed)
# set-hook -g client-focus-in        'refresh-client -S'
# set-hook -g client-focus-out       'refresh-client -S'
# set-hook -g after-select-window    'refresh-client -S'
# set-hook -g after-new-window       'refresh-client -S'
# set-hook -g window-pane-changed    'refresh-client -S'
# set-hook -g window-layout-changed  'refresh-client -S'

If you need live data that tmuxship apply cannot capture (battery, git status, etc.), override a specific side with runtime rendering:

set -g status-right '#(tmuxship right)'
set -g window-status-format         '#(TMUX_SHIP_TARGET="#{window_id}" tmuxship center)'
set -g window-status-current-format '#(TMUX_SHIP_TARGET="#{window_id}" tmuxship center)'

Set TMUX_SHIP_TARGET to a tmux format string like #{window_id} so tmuxship queries data for the correct window rather than the active one.

To inspect what tmuxship apply would generate before applying:

tmuxship emit-tmux-conf

Recognized custom module names for generated config:

• prefix_active and session_normal (left config) → generates status-left around tmux-native #S
• window_active, window_inactive, window_zoom (center config) → generates window status around #I, #W, and #{window_zoomed_flag}; separator text is controlled by TMUX_SHIP_WINDOW_SEPARATOR
• Right config is always runtime-rendered as #(tmuxship right)

Left: session name · Center: window list (active highlighted) · Right: time, host, window count

Normal	Prefix active

The session name is subtle in normal state and gets a bright green background when you press the tmux prefix key.

starship.toml (set via TMUX_SHIP_LEFT_CONFIG):

"$schema" = 'https://starship.rs/config-schema.json'
format = "$custom"
add_newline = false

# Shown when the prefix key is active
[custom.prefix_active]
when = 'test "${TMUX_CLIENT_PREFIX:-0}" = "1"'
command = 'printf "%s" "${TMUX_SESSION_NAME}"'
format = "[$output]($style) "
style = "bg:#95E6CB bold"

# Shown in normal state
[custom.session_normal]
when = 'test "${TMUX_CLIENT_PREFIX:-0}" != "1"'
command = 'printf "%s" "${TMUX_SESSION_NAME}"'
format = "[$output]($style) "
style = "fg:#565B66"

Active	Inactive	Zoomed

Active windows get a bold, highlighted style. Inactive windows are muted. Zoomed windows show an indicator.

.center.toml (set via TMUX_SHIP_CENTER_CONFIG):

format = "$custom"
add_newline = false

[custom.window_active]
when = 'test "${TMUX_WINDOW_ACTIVE:-0}" = "1"'
command = 'printf "%s:%s" "${TMUX_WINDOW_INDEX}" "${TMUX_WINDOW_NAME}"'
format = "[$output]($style)"
style = "bg:#313244 fg:#CDD6F4 bold"

[custom.window_inactive]
when = 'test "${TMUX_WINDOW_ACTIVE:-0}" != "1"'
command = 'printf "%s:%s" "${TMUX_WINDOW_INDEX}" "${TMUX_WINDOW_NAME}"'
format = "[$output]($style)"
style = "fg:#6C7086"

# Optional: show an icon when the active window is zoomed
[custom.window_zoom]
when = 'test "${TMUX_WINDOW_ACTIVE:-0}" = "1" && test "${TMUX_WINDOW_ZOOMED_FLAG:-0}" = "1"'
command = 'printf "🔍"'
format = " $output"

.right.toml (set via TMUX_SHIP_RIGHT_CONFIG):

"$schema" = 'https://starship.rs/config-schema.json'

format = "$time$custom"
add_newline = false

[time]
disabled = false
format = "[$time]($style) "
style = "fg:#89B4FA"
time_format = "%H:%M:%S"

[custom.host]
when = "true"
shell = "bash"
command = 'printf "%s" "${TMUX_HOST_SHORT:-$(hostname -s)}"'
format = "on [$output]($style) "
style = "fg:#A6E3A1"

[custom.window_count]
when = "true"
shell = "bash"
command = 'printf "%s" "${TMUX_SESSION_WINDOWS}"'
format = "[󰖲 $output]($style)"
style = "fg:#CBA6F7"

Combine built-in Starship modules with custom tmux-aware modules for a rich left status.

advanced-left.toml:

"$schema" = 'https://starship.rs/config-schema.json'

format = "$custom$directory$git_branch$git_status"
add_newline = false

# Session name with prefix highlighting
[custom.session_prefix]
shell = "bash"
when = 'test "${TMUX_CLIENT_PREFIX:-0}" = "1"'
command = 'printf "󰇄 %s" "${TMUX_SESSION_NAME:-?}"'
format = "[$output]($style) "
style = "bg:#95E6CB fg:#1E1E2E bold"

[custom.session_normal]
shell = "bash"
when = 'test "${TMUX_CLIENT_PREFIX:-0}" != "1"'
command = 'printf "󰇄 %s" "${TMUX_SESSION_NAME:-?}"'
format = "[$output]($style) "
style = "fg:#565B66"

# Current directory (from the active pane's CWD)
[directory]
format = "[$path]($style) "
style = "fg:#89B4FA"
truncation_length = 3
truncate_to_repo = true

# Git branch
[git_branch]
format = "on [$symbol$branch]($style) "
symbol = ""
style = "fg:#A6E3A1"

# Git status indicators
[git_status]
format = '([\[$all_status$ahead_behind\]]($style) )'
style = "fg:#F9E2AF"

See the examples/ directory for all available configuration samples.

All tmux variables are automatically injected into the Starship environment with a TMUX_ prefix.

By default, tmuxship fetches all common tmux variables. To reduce overhead, specify only the variables you need:

set -g status-left '#(TMUX_SHIP_TMUX_VARS="session_name,window_index" tmuxship left)'

1. tmux invokes tmuxship via #(tmuxship left) (or another side).
2. tmuxship queries tmux and exposes variables as TMUX_* environment variables.
3. Starship is executed with the resolved config file.
4. ANSI color codes from Starship output are converted to tmux format strings.
5. The result is written to stdout for tmux to render.

Contributions are welcome. Please see CONTRIBUTING.md for details.

cargo test

Screenshots are generated from Starship ANSI output using ansisvg:

# Install ansisvg (requires Go)
go install github.com/wader/ansisvg@latest

# Generate screenshots from example configs
./scripts/generate-screenshots.sh

Output SVGs are placed in screenshots/.

MIT