[tmux.app]
tmux 3.8

Docs · Terminals · Ghostty 1.4 · tmux 3.8

Ghostty + tmux: true color, terminfo and clipboard

tmux runs well in Ghostty with almost no setup: Ghostty sets TERM=xterm-ghostty and COLORTERM=truecolor, and tmux 3.8 recognizes Ghostty and turns on 24-bit color, undercurl, extended keys and more by itself. The one thing that regularly breaks is SSH: servers without Ghostty's terminfo stop tmux with missing or unsuitable terminal: xterm-ghostty. Ghostty does not support tmux control mode (tmux -CC) yet.

Updated Tested on tmux 3.87 min read

On this page
  1. True color and terminfo in Ghostty + tmux
  2. Fix "missing or unsuitable terminal: xterm-ghostty" over SSH
  3. Ghostty config for tmux users
  4. Clipboard: OSC 52 from tmux to Ghostty
  5. Does Ghostty support tmux control mode (tmux -CC)?
  6. Ghostty vs tmux: splits, tabs and persistence
  7. Ghostty, tmux and cmux
  8. FAQ

Quick answer

How do I set up tmux in Ghostty?

  • In ~/.tmux.conf: set -g default-terminal "tmux-256color" and set -as terminal-features ",xterm-ghostty:RGB" (the second line only matters before tmux 3.6).
  • Error missing or unsuitable terminal: xterm-ghostty on a server: run infocmp -x xterm-ghostty | ssh host -- tic -x - once from your machine, or connect with ghostty +ssh host (Ghostty 1.4).
  • Start tmux in every Ghostty window: command = tmux new-session -A -s main in Ghostty's config.
  • Clipboard: works out of the box. Ghostty allows OSC 52 writes by default and tmux sends copies that way.
  • tmux -CC: not supported by Ghostty 1.4; use plain tmux, or iTerm2 for control mode.

Ghostty facts are from ghostty.org documentation and the 1.4.0 release notes (Ghostty 1.4.0, released 27 October 2026), read 28 October 2026. tmux behavior was tested on tmux 3.8 and checked against its source; we had no Ghostty GUI on the test machine, so Ghostty itself was not run.

True color and terminfo in Ghostty + tmux

Two terminal types are involved. Ghostty identifies itself to programs as xterm-ghostty; tmux reads that terminfo entry to learn what Ghostty can draw. Programs inside tmux see whatever default-terminal says, which should be tmux-256color.

~/.tmux.conf (Ghostty)
# TERM inside tmux
set -g default-terminal "tmux-256color"

# 24-bit color for Ghostty. tmux 3.8 detects this itself,
# and 3.6+ also trusts COLORTERM=truecolor; harmless to keep.
set -as terminal-features ",xterm-ghostty:RGB"

# Shift+Enter, Ctrl+Shift+key etc. reach programs (Claude Code, Neovim)
set -s extended-keys on

# Image previews (Yazi etc.) and Claude Code notifications
set -g allow-passthrough on
set -ga update-environment TERM_PROGRAM

What tmux 3.8 detects by itself. When a client attaches, tmux asks the terminal for its name. If the reply starts with ghostty, tmux 3.8 applies its built-in Ghostty feature set: RGB color, 256 colors, bracketed paste, clipboard, mouse, strikethrough, title, cursor color and style, extended keys, focus, overline, hyperlinks, current-directory reporting (OSC 7), synchronized output, undercurl and colored underlines, the OSC 9;4 progress bar, and left/right margins (the margins are new in 3.8). Check what was detected with tmux display -p '#{client_termfeatures}'.

On older tmux the explicit RGB line is what turns on true color. We checked the COLORTERM rule directly: with COLORTERM=truecolor, tmux 3.8 listed RGB for the client and tmux 3.4 did not. If colors still look washed out, see true color in tmux.

Fix "missing or unsuitable terminal: xterm-ghostty" over SSH

SSH passes your TERM to the server. If the server has no xterm-ghostty entry, tmux refuses to start and other programs complain too. This is what it looks like on Ubuntu 24.04, whose ncurses 6.4 does not include Ghostty's entry:

Real screenshot · tmux 3.8tmux, infocmp and clear on a server without Ghostty's terminfo.
tmux, infocmp and clear on a server without Ghostty's terminfo.
How this was captured

Captured 2026-10-29 04:51 UTC from a real xterm window running tmux 3.8 on Ubuntu 24.04. Nothing is mocked up. The commands that set up the screen:

tmux new-session -d -s work -x 100 -y 11
tmux send-keys -t work 'clear; TMUX= TERM=xterm-ghostty tmux -L remote new; TERM=xterm-ghostty infocmp | head -1; TERM=xterm-ghostty clear' Enter
Which TERM each layer uses with Ghostty, SSH and tmux Ghostty sets TERM to xterm-ghostty. When you SSH to a server, that TERM is sent along, so the tmux client on the server must find an xterm-ghostty terminfo entry or it stops with missing or unsuitable terminal. Fixes are installing the entry on the server with infocmp and tic, ghostty +ssh in Ghostty 1.4, or sending xterm-256color instead. Inside tmux, panes use default-terminal, normally tmux-256color. Ghostty your Mac or PC TERM=xterm-ghostty ssh Server tmux client looks up xterm-ghostty in terminfo missing → won't start tmux server · panes default-terminal TERM=tmux-256color Fix once per server: infocmp -x xterm-ghostty | ssh host -- tic -x - or ghostty +ssh (1.4) · or SetEnv TERM=xterm-256color
The tmux client on the server needs xterm-ghostty; the panes inside tmux use tmux-256color.

Fix 1: copy the terminfo entry to the server (once per server)

run on your own machine, in Ghostty
# Compile your local xterm-ghostty entry on the server
infocmp -x xterm-ghostty | ssh user@server -- tic -x -

This is the command from Ghostty's terminfo docs. Run as a normal user, tic cannot write to the system database and puts the entry in ~/.terminfo; we tested exactly that pipe with a non-root account and infocmp on that account then found the entry. Ghostty's docs add two notes: tic may warn that "older tic versions may treat the description field as an alias", which you can ignore, and macOS before Sonoma ships an infocmp too old for this, so use Homebrew's (brew install ncurses, then /opt/homebrew/opt/ncurses/bin/infocmp).

Fix 2: let Ghostty do it (Ghostty 1.4: ghostty +ssh)

Ghostty 1.4
# One connection
ghostty +ssh user@server

# Or every ssh you type
alias ssh='ghostty +ssh --'

Ghostty 1.4's +ssh wraps ssh: before connecting it installs Ghostty's bundled terminfo on the server, forwards COLORTERM, TERM_PROGRAM and TERM_PROGRAM_VERSION, and falls back to TERM=xterm-256color if the install fails (for example when the server has no tic). It remembers which hosts are done; ghostty +ssh-cache manages that list. The older shell-integration features do the same through your shell, and in 1.4 they call +ssh too:

~/.config/ghostty/config
shell-integration-features = ssh-terminfo,ssh-env

Both only apply to an ssh you type in an interactive shell. Scripts, git, scp, rsync and mosh run their own ssh and are not covered, per Ghostty's SSH docs.

Fix 3: send a TERM every server knows

~/.ssh/config (OpenSSH 8.7+)
Host legacy-box
  SetEnv TERM=xterm-256color

This always works but loses features xterm-256color does not describe, such as styled underlines. With sudo, a similar error can appear because sudo resets TERMINFO; Ghostty's sudo shell-integration feature handles that. More terminal errors are on troubleshooting.

Ghostty config for tmux users

~/.config/ghostty/config
# Attach to (or create) tmux session "main" in every new window and tab
command = tmux new-session -A -s main
# ...or only in the first window Ghostty opens:
# initial-command = tmux new-session -A -s main

# macOS: make Option act as Alt, for M- bindings in tmux and Neovim
macos-option-as-alt = true

# Install terminfo on SSH hosts and forward COLORTERM etc. (opt-in)
shell-integration-features = ssh-terminfo,ssh-env

# Defaults, shown for clarity: programs may write the clipboard (OSC 52),
# reading it asks first
clipboard-write = allow
clipboard-read = ask

command applies to every new window, tab and split, so every Ghostty split would attach to the same session too. If you want Ghostty splits for local shells, use initial-command instead, which only runs in the first window Ghostty creates. With arguments, Ghostty runs the command through /bin/sh -c, so tmux must be in the PATH that sh sees (on macOS with Homebrew, use the full path /opt/homebrew/bin/tmux if Ghostty cannot find it).

macos-option-as-alt is already true by default on the U.S. Standard and U.S. International layouts; set it explicitly on other layouts if Option combinations type characters instead of reaching tmux.

Clipboard: OSC 52 from tmux to Ghostty

When you copy in tmux's copy mode, tmux sends the text to the terminal with the OSC 52 escape sequence (the default set-clipboard external). Ghostty's default clipboard-write = allow accepts it, so copying works locally and over SSH with no extra tools.

~/.tmux.conf (copy mode)
# "external" (default): tmux copies reach Ghostty's clipboard.
# "on": programs inside tmux (Neovim, Claude Code) may set it too.
set -s set-clipboard on

# vi keys in copy mode: v to start, y to copy
setw -g mode-keys vi
bind-key -T copy-mode-vi v send -X begin-selection
bind-key -T copy-mode-vi y send -X copy-pipe-and-cancel

We tested the difference on tmux 3.8: with external, an OSC 52 sequence printed by a program in the pane was dropped; with on it reached the terminal and was also saved as a tmux buffer. Ghostty 1.4 also added the Kitty clipboard protocol for rich content; tmux handles OSC 52 (plain text). Selection, buffers and pasting are covered in copy mode and the clipboard. To select text with the mouse past tmux (mouse is on by default in 3.8), hold Shift while dragging.

Does Ghostty support tmux control mode (tmux -CC)?

No, not as of Ghostty 1.4.0. Control mode is the protocol iTerm2 uses to show tmux windows as native tabs and splits. Ghostty's terminal library has been learning to parse it: the 1.3.0 notes list "significantly more tmux control mode parsing, but not hooked up to the GUI yet", and the 1.4.0 notes still say "tmux control mode is still not hooked up to the GUI." The 1.4.0 notes also fix security issues where malicious output could crash Ghostty 1.3.0 and 1.3.1 through the control-mode parser, so update if you are on 1.3.

If you run tmux -CC in a terminal that does not speak control mode, you get protocol text or a blank screen instead of tmux, and Ctrl+c does nothing. Press Enter on the empty line: in our test on tmux 3.8 an empty line made the control client exit (the session keeps running). Then attach normally with tmux attach. For native tmux windows on macOS today, see iTerm2 and tmux -CC.

Ghostty vs tmux: splits, tabs and persistence

Ghostty and tmux are different kinds of tool, and most people who search "tmux vs Ghostty" end up using both. Ghostty, created by Mitchell Hashimoto, is a terminal emulator: it draws text on your screen, with GPU rendering and native tabs and splits, but it does no multiplexing in the tmux sense. tmux is a multiplexer that runs inside any terminal and keeps sessions alive on the machine where it runs.

Ghostty tabs and splitstmux windows and panes
Survives closing the windowNo, the shells endYes, detach and reattach
Survives an SSH dropNoYes, on the server
Restores the layout after restartwindow-save-state restores windows, tabs and splits (not running programs)With tmux-resurrect
Same layout from another computerNoYes, attach over SSH
ScriptableKeybinds and actions; scripting is plannedEvery action is a command
Modal key tablesKey tables and chained keybinds (1.3+)Prefix key and key tables
RenderingGPU, native UIWhatever the outer terminal does

A common split: Ghostty splits for quick local shells, tmux on servers and for anything long-running. Ghostty's command setting makes tmux the default if you live in it.

Ghostty, tmux and cmux

cmux is a macOS terminal app built on libghostty, Ghostty's rendering library (it is not a fork of Ghostty), with vertical tabs and notifications aimed at running AI coding agents. Like Ghostty it is a terminal, so it does not replace tmux on a remote server; you can run tmux inside it the same way. How it compares in detail is on cmux vs tmux, and running agents in tmux on Claude Code in tmux.

FAQ

How do I configure truecolor in Ghostty with tmux?

Set default-terminal "tmux-256color" and add set -as terminal-features ",xterm-ghostty:RGB" to ~/.tmux.conf, then reattach. tmux 3.8 detects Ghostty's 24-bit color by itself and 3.6+ also accepts COLORTERM=truecolor, so on current tmux the line is a safety net. In Neovim, also set termguicolors.

Why does tmux say missing or unsuitable terminal: xterm-ghostty?

You are on a machine without Ghostty's terminfo entry, usually a server you reached over SSH. Install it with infocmp -x xterm-ghostty | ssh host -- tic -x -, connect with ghostty +ssh (Ghostty 1.4), or send TERM=xterm-256color for that host.

Does Ghostty support tmux -CC control mode?

No. Ghostty 1.4.0's release notes say tmux control mode "is still not hooked up to the GUI". Use normal tmux in Ghostty, or iTerm2 if you want tmux windows as native tabs.

Should I use Ghostty splits or tmux panes?

Use tmux when the work must survive closing the window or an SSH drop, or when you want the same layout from another machine. Ghostty splits are fine for quick local shells. Many people use both.

Do Kitty graphics images work in tmux in Ghostty?

Partly. tmux does not implement the Kitty graphics protocol, but with set -g allow-passthrough on tools that know about tmux, such as Yazi, can send images straight to Ghostty. Images may not move or clear correctly when you switch panes or windows.

Keep learning

Something wrong or out of date on this page? Email hello@tmux.app and we will fix it.