Set up tmux with the Gruvbox theme

Verified with tmux 3.6b · Ghostty 1.3.1 · macOS 27.0

1. 01Step 1: Install tmuxThe terminal multiplexer itself.

   Install tmux with Homebrew:

   brew install tmux

   Check the version:

   tmux -V

   tmux 3.6b

2. 02Step 2: Install TPM, the plugin managerDownloads and loads tmux plugins, including the Gruvbox theme.

   TPM, the Tmux Plugin Manager, installs the plugins you list in your tmux config. Download it into the folder where tmux plugins live:

   git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

3. 03Step 3: Write your tmux configTrue color in Ghostty, the settings Claude Code needs, and the Gruvbox plugin.

   tmux reads its settings from ~/.tmux.conf. This command backs up the file you already have, if any, then writes a new one in three parts:

   • Color: tells tmux that Ghostty can show full 24-bit color.
   • Claude Code: lets notifications reach Ghostty and makes Shift+Enter insert a new line, as the Claude Code docs recommend.
   • Plugins: loads TPM, the sensible defaults plugin, and the Gruvbox theme, with TPM's run line kept at the very bottom.

   [ -f ~/.tmux.conf ] && cp ~/.tmux.conf ~/.tmux.conf.bak-$(date +%Y%m%d-%H%M%S)
   cat > ~/.tmux.conf <<'EOF'
   # 24-bit color inside Ghostty
   set -g default-terminal "tmux-256color"
   set -as terminal-features ",xterm-ghostty:RGB"
   
   # Claude Code inside tmux: Shift+Enter newlines, notifications, progress bar
   # https://code.claude.com/docs/en/terminal-config#configure-tmux
   set -g allow-passthrough on
   set -s extended-keys on
   set -as terminal-features 'xterm*:extkeys'
   
   # Plugins
   set -g @plugin 'tmux-plugins/tpm'
   set -g @plugin 'tmux-plugins/tmux-sensible'
   set -g @plugin 'egel/tmux-gruvbox'
   set -g @tmux-gruvbox 'dark' # or 'dark256', 'light', 'light256'
   
   # Start TPM (keep this line at the very bottom)
   run '~/.tmux/plugins/tpm/tpm'
   EOF

   The first setting needs your Mac to know a terminal type called tmux-256color. This check prints ok if it does:

   infocmp tmux-256color >/dev/null && echo ok

   If it prints an error instead, change tmux-256color to screen-256color in ~/.tmux.conf:

   sed -i '' 's|"tmux-256color"|"screen-256color"|' ~/.tmux.conf

4. 04Step 4: Start tmux and install the pluginsOne key combination downloads the Gruvbox theme and turns it on.

   Start a tmux session named main:

   tmux new -s main

   Now install the plugins listed in your config. tmux shortcuts start with the prefix key, Ctrl+b. Press Ctrl+b, let go, then press Shift+i (a capital I).

   TPM downloads the plugins and reloads tmux, and the status bar at the bottom switches to the Gruvbox colors. When it says Done, press the key it names, Enter or Escape, to continue.

   Check that tmux sees Ghostty's full color and extended keys support:

   tmux display -p '#{client_termfeatures}'

   The list should include RGB and extkeys, for example:

   bpaste,ccolour,clipboard,cstyle,extkeys,focus,RGB,title

5. 05Step 5: Reload after you edit the configApply changes to ~/.tmux.conf without closing tmux.

   tmux reads ~/.tmux.conf when it starts. After you change the file, run this inside tmux to apply the change right away:

   tmux source ~/.tmux.conf

   If you add a new @plugin line, press Ctrl+b then Shift+i again to download it.

6. 06Step 6: Switch between dark and lightPick one of the four Gruvbox variants, and tweak the status bar if you like.

   The theme has four variants. dark and light use the exact Gruvbox colors, which relies on the 24-bit color setting from your config. dark256 and light256 use the nearest colors from the older 256-color palette. Without any setting, the plugin uses dark256. This command backs up your config, switches the variant to light, and reloads tmux. Replace light with any of the four names.

   cp ~/.tmux.conf ~/.tmux.conf.bak-$(date +%Y%m%d-%H%M%S)
   sed -i '' "s|^set -g @tmux-gruvbox .*|set -g @tmux-gruvbox 'light'|" ~/.tmux.conf
   tmux source ~/.tmux.conf

   The theme also has a few optional settings. Each one goes in ~/.tmux.conf above the run line, because the theme reads them when TPM loads it.

   # See-through status bar (needs tmux 3.2 or later)
   set -g @tmux-gruvbox-statusbar-alpha 'true'
   
   # Left side: the session name (this is the default)
   set -g @tmux-gruvbox-left-status-a '#S'
   
   # Right side: date, time and host name (US date format shown)
   set -g @tmux-gruvbox-right-status-x '%m/%d/%Y'
   set -g @tmux-gruvbox-right-status-y '%H:%M'
   set -g @tmux-gruvbox-right-status-z '#h'

   To add one, open the file in nano, the simple editor that comes with macOS:

   nano ~/.tmux.conf

   Paste the line above the run line, press Ctrl+O then Enter to save, and Ctrl+X to exit. Then reload tmux as in the previous step.

7. 07Step 7: Match Ghostty's colors to GruvboxoptionalSwitch Ghostty to its built-in Gruvbox themes, which follow your Mac's light or dark mode.

   Ghostty ships with Gruvbox themes, so the whole window can match the tmux status bar. This replaces the coolnight colors from the Ghostty guide.

   This command backs up your Ghostty config, then points its theme line at Gruvbox Dark in dark mode and Gruvbox Light in light mode. If the file has no theme line yet, it adds one instead.

   f=~/.config/ghostty/config.ghostty
   mkdir -p ~/.config/ghostty && touch "$f"
   cp "$f" "$f.bak-$(date +%Y%m%d-%H%M%S)"
   if grep -q '^theme = ' "$f"; then
     sed -i '' 's|^theme = .*|theme = dark:Gruvbox Dark,light:Gruvbox Light|' "$f"
   else
     echo 'theme = dark:Gruvbox Dark,light:Gruvbox Light' >> "$f"
   fi
   ghostty +validate-config

   The theme line in your config now reads:

   theme = dark:Gruvbox Dark,light:Gruvbox Light

   Press Cmd+Shift+, to reload Ghostty. For an exact match, use the tmux dark variant with Gruvbox Dark: both use the same #282828 background. Ghostty follows your Mac's appearance on its own, but tmux does not, so switch the tmux variant to light yourself when you use light mode.

8. 08Step 8: tmux cheat sheetThe handful of keys and commands you will use every day.

   Every tmux shortcut starts with the prefix, Ctrl+b. Press and release it, then press the next key.

   Keys	What it does
   Ctrl+b then %	Split the pane into left and right
   Ctrl+b then "	Split the pane into top and bottom
   Ctrl+b then an arrow key	Move to the pane in that direction
   Ctrl+b then z	Zoom the current pane to full size, or back
   Ctrl+b then x	Close the current pane, after you confirm with y
   Ctrl+b then c	Open a new window, like a tab
   Ctrl+b then n or p	Go to the next or previous window
   Ctrl+b then a number	Go to that window
   Ctrl+b then d	Detach, leaving everything running in the background

   After you detach or close Ghostty, your session keeps running. List your sessions:

   tmux ls

   Reattach to the one named main:

   tmux attach -t main

   When Claude Code runs inside tmux, its Ctrl+B shortcut, which sends a running task to the background, needs two presses, because tmux takes the first one as its prefix.