Marketplace configuring-tmux

Configures tmux status bars, installs frameworks and plugins, adds widgets and scripts, and sets up multiple status bars. Use when working with oh-my-tmux, Catppuccin, or tmux-powerline; adding weather/finance/clock/news widgets; troubleshooting why bar changes aren't appearing; or setting up tmux on a new machine.

install

source · Clone the upstream repo

git clone https://github.com/aiskillstore/marketplace

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/aiskillstore/marketplace "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/ibrahimhka/configuring-tmux" ~/.claude/skills/aiskillstore-marketplace-configuring-tmux && rm -rf "$T"

manifest: skills/ibrahimhka/configuring-tmux/SKILL.md

source content

Configuring tmux

Step 0: Choose a Framework

Ask the user which framework they want before touching any config.

Option 1: oh-my-tmux

cd ~ && git clone https://github.com/gpakosz/.tmux.git
ln -sf .tmux/.tmux.conf .tmux.conf
cp .tmux/.tmux.conf.local .tmux.conf.local

Theming via

tmux_conf_theme_*

variables in

~/.tmux.conf.local

— never edit

~/.tmux.conf

Gotcha: its theming layer owns bar 0 and overrides raw
```
set -g status-right
```
— use
```
status-format[]
```
for extra bars

Option 2: Catppuccin (TPM-based, no clone needed)

set -g @plugin 'catppuccin/tmux#v2.1.3'
set -g @catppuccin_flavor 'mocha'
set -g @catppuccin_status_modules_right "application session date_time"

Module list controls bar 0 — add custom
```
#()
```
calls via
```
status-right-append
```
Extra bars use
```
status-format[]
```
directly

Option 3: tmux-powerline

git clone https://github.com/erikw/tmux-powerline.git ~/.config/tmux-powerline
set-option -g status-left "#(~/.config/tmux-powerline/powerline.sh left)"
set-option -g status-right "#(~/.config/tmux-powerline/powerline.sh right)"

Requires Nerd Font or Powerline-patched font
Segments live in
```
~/.config/tmux-powerline/segments/
```

Option 4: User-provided framework

Ask for: repo URL, install method, where customizations live, how it handles status content. Then apply the patterns below.

Plugin Setup (all frameworks)

# Install TPM
git clone https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm

# Essential plugins
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @plugin 'tmux-plugins/tmux-cpu'          # #{cpu_percentage} #{ram_percentage}
set -g @plugin 'tmux-plugins/tmux-net-speed'    # #{net_speed_up} #{net_speed_down}

set -g @continuum-restore 'on'
set -g @continuum-save-interval '10'
set -g @resurrect-capture-pane-contents 'on'

run '~/.config/tmux/plugins/tpm/tpm'
# Install: prefix + I

Multiple Status Bars

tmux 3.2+ supports 2–5 bars. The correct syntax is

status-format[]

array — not

status2-right

(invalid, will error).

set -g status 3

# Bar 1: widgets row
set -g status-format[1] "#[bg=#1a1b26,fg=#c0caf5,align=right]#(~/.config/tmux/scripts/weather.sh)  #(~/.config/tmux/scripts/finance.sh)  #[fg=#1e3a8a,bg=#b8970d,bold]PT #(TZ=America/Los_Angeles date +%H:%M) EST #(TZ=America/New_York date +%H:%M)#[default]"

# Bar 2: news ticker
set -g status-format[2] "#[bg=#16161e,fg=#e0af68,align=right]  #(~/.config/tmux/scripts/news-ticker.sh)"

With

status-position top

and

status 3

Bar 0  ← framework owns (oh-my-tmux / Catppuccin)
Bar 1  ← status-format[1]  — configure freely
Bar 2  ← status-format[2]  — configure freely
──────────────────────────────
Terminal panes

Verify:

tmux show-options -g status

(must equal your total bar count)

Widget Scripts

Single-line output rule

Scripts in

#()

must emit one line. Multi-line output corrupts the bar.

Caching pattern (required for network scripts)

#!/bin/bash
CACHE="/tmp/my-widget-cache"
CACHE_AGE=300

if [ -f "$CACHE" ]; then
    age=$(( $(date +%s) - $(stat -c %Y "$CACHE") ))
    [ "$age" -lt "$CACHE_AGE" ] && cat "$CACHE" && exit 0
fi

python3 << 'PYEOF' | tee "$CACHE"
# fetch and print ONE line
PYEOF

World clocks (no cache needed)

# In status-format[]: use %H:%M directly
"PT #(TZ=America/Los_Angeles date +%H:%M) EST #(TZ=America/New_York date +%H:%M)"

# In oh-my-tmux tmux_conf_theme_status_right: escape % as %%
"PT #(TZ=America/Los_Angeles date +%%H:%%M)"

Rotating news ticker

#!/bin/bash
CACHE="/tmp/news-cache"  # one headline per line, refreshed by background fetch
[ ! -s "$CACHE" ] && echo "Loading..." && exit 0
count=$(wc -l < "$CACHE")
idx=$(( ($(date +%s) / 20) % count ))   # rotates every 20s
sed -n "$((idx + 1))p" "$CACHE"

Finance widget (Yahoo Finance v8)

Use

-A "Mozilla/5.0"

— Yahoo blocks default curl UA:

curl -sf --max-time 4 -A "Mozilla/5.0 (X11; Linux x86_64)" \
  "https://query1.finance.yahoo.com/v8/finance/chart/BTC-USD?interval=1d&range=1d"

oh-my-tmux: Bar 0 Reference

# ~/.tmux.conf.local
tmux_conf_theme_status_right="#{prefix}#{mouse} 🌿 #[fg=#000,bg=#2ea043,bold]#(git -C #{pane_current_path} symbolic-ref --short HEAD 2>/dev/null)#[default] #[fg=#fff,bg=#cc1111,bold]⚡#{cpu_percentage}/💾#{ram_percentage}#[default]"
tmux_conf_theme_status_right_fg="#000000,#000000,#000000"
tmux_conf_theme_status_right_bg="#2ea043,#1155cc,#2ea043"
tmux_conf_theme_status_right_length=300

Common Mistakes

Mistake	Fix
`set -g status-right` overridden	Use `tmux_conf_theme_status_right=` (oh-my-tmux) or framework equivalent
`status2-right` → invalid option	Use `set -g status-format[1] "..."`
New bars not visible	`tmux show-options -g status` must equal bar count
Bar appears blank	Script must output exactly one non-empty line
Script works in terminal, blank in bar	tmux `#()` has minimal PATH — use `~/` or absolute paths
`%%` vs `%` confusion	`%%` in `tmux_conf_theme_*` ; `%H:%M` directly in `status-format[]`

Reload

tmux source-file ~/.tmux.conf        # full reload (re-applies framework theming)
tmux source-file ~/.tmux.conf.local  # local overrides only