tmuxship 0.1.3

A Starship-to-tmux adapter that renders tmux-ready status lines from Starship JSON output
Documentation

tmuxship

Crates.io License: MIT

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.

Features

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

tmux status bar rendered by tmuxship

Quick Start

1. Install tmuxship

cargo install tmuxship

2. Copy the example configs

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

3. 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'

4. Reload tmux

tmux source ~/.tmux.conf

See the examples/ directory for complete configuration samples.

Installation

From crates.io

cargo install tmuxship

From source

cargo install --path .

Usage

Commands

Command Description
tmuxship left Render the left status segment
tmuxship right Render the right status segment
tmuxship center Render the window status segment
tmuxship full Render all segments
tmuxship emit-tmux-conf Print the generated tmux config
tmuxship apply Apply the generated config to the running tmux server

Config Resolution

tmuxship resolves Starship config files in the following order (where <side> is left, right, or center):

  1. --config flag
  2. TMUX_SHIP_<SIDE>_CONFIG (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

Available tmux Variables

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

Session

Variable Description
TMUX_SESSION_NAME Current session name
TMUX_SESSION_ID Session ID
TMUX_SESSION_CREATED Session creation timestamp
TMUX_SESSION_ATTACHED Number of attached clients
TMUX_SESSION_WINDOWS Number of windows

Window

Variable Description
TMUX_WINDOW_ID Window ID
TMUX_WINDOW_INDEX Window index
TMUX_WINDOW_NAME Window name
TMUX_WINDOW_ACTIVE 1 if active, 0 otherwise
TMUX_WINDOW_FLAGS Window flags
TMUX_WINDOW_LAYOUT Window layout
TMUX_WINDOW_PANES Number of panes
TMUX_WINDOW_WIDTH / TMUX_WINDOW_HEIGHT Window dimensions
TMUX_WINDOW_ZOOMED_FLAG 1 if zoomed, 0 otherwise

Pane

Variable Description
TMUX_PANE_ID Pane ID
TMUX_PANE_INDEX Pane index
TMUX_PANE_TITLE Pane title
TMUX_PANE_CURRENT_PATH Current working directory
TMUX_PANE_CURRENT_COMMAND Running command
TMUX_PANE_PID Process ID
TMUX_PANE_WIDTH / TMUX_PANE_HEIGHT Pane dimensions
TMUX_PANE_ACTIVE 1 if active, 0 otherwise
TMUX_PANE_AT_TOP / TMUX_PANE_AT_BOTTOM / TMUX_PANE_AT_LEFT / TMUX_PANE_AT_RIGHT Edge position flags

Client

Variable Description
TMUX_CLIENT_PREFIX 1 if prefix key is active, 0 otherwise
TMUX_CLIENT_WIDTH / TMUX_CLIENT_HEIGHT Terminal dimensions
TMUX_CLIENT_TERMNAME Terminal name

Host

Variable Description
TMUX_HOST Full hostname
TMUX_HOST_SHORT Short hostname

Examples

Full status bar

tmux status bar rendered by tmuxship

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

Left status — session with prefix highlighting

Normal Prefix active
left normal left prefix

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"

Center — window list with active/inactive styling

Active Inactive Zoomed
window active window inactive window 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 — time, host, and window count

right status

.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"

Advanced left — session, git branch, and directory

advanced left

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 examples/ for all available configuration samples.

tmux Configuration

A complete ~/.tmux.conf example using tmuxship:

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 client-focus-in        'refresh-client -S'
set-hook -g pane-focus-in          'refresh-client -S'
set-hook -g window-pane-changed    'refresh-client -S'
set-hook -g window-layout-changed  'refresh-client -S'

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

# Optional: lower interval for clock or frequently changing data
set -g status-interval 2

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

Generated Config vs. Runtime Rendering

tmuxship apply generates static tmux options at startup. For segments that need live data (battery, git status, etc.), use runtime rendering instead:

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)

Advanced Configuration

Limiting Fetched Variables

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)'

How It Works

  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

Contributing

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

Development

cargo test

Generating Screenshots

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/.

License

MIT