tmux-claude-code

Optimized tmux configuration for Claude Code. Eliminates flicker, fixes input lag, and provides a polished dark theme.

The Problem

Running Claude Code inside tmux with default settings causes:

• Screen flicker/tearing during streaming output (missing allow-passthrough)
• Input lag after pressing Escape (default 500ms escape-time)
• Broken key combos like Ctrl+Shift (missing extended-keys)
• Scrollback overflow during long sessions (default 2,000 line history-limit)
• Clipboard issues in SSH/nested tmux (missing set-clipboard)

This project fixes all of them with a single install.

Quick Start

Option 1: Full Config (recommended for new tmux users)

git clone https://github.com/sethdford/tmux-claude-code.git
cd tmux-claude-code
./install.sh

This installs a complete, opinionated tmux config with a dark theme, vim keybindings, and all Claude Code fixes.

Option 2: Overlay Only (keep your existing config)

git clone https://github.com/sethdford/tmux-claude-code.git
cd tmux-claude-code
./install.sh --overlay

This adds only the 8 critical Claude Code settings to your existing config. Your keybindings, theme, and plugins are untouched.

Option 3: Manual

Add these lines to your ~/.tmux.conf:

set -g allow-passthrough on
set -g extended-keys on
set -as terminal-features 'xterm*:extkeys'
set -sg escape-time 0
set -g set-clipboard on
set -g history-limit 250000
set -g focus-events on
set -g mouse on
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

Then reload: tmux source-file ~/.tmux.conf

Diagnostic

Run the doctor to check your setup:

./doctor.sh

Output looks like:

  tmux + Claude Code — Doctor
  ══════════════════════════════════════════

1. tmux Version
  PASS  tmux 3.5a — all features supported

2. Claude Code Compatibility
  PASS  allow-passthrough: on (DEC 2026 synchronized output — no flicker)
  PASS  extended-keys: on (modifier key combos work)
  PASS  escape-time: 0ms (no input delay)
  PASS  set-clipboard: on (OSC 52 clipboard works)
  PASS  history-limit: 250000 (sufficient for Claude Code streaming)
  PASS  focus-events: on (TUI focus tracking works)
  PASS  default-terminal: tmux-256color (full color support)
  PASS  mouse: on (scroll + click + resize)
...

What Each Setting Does

Setting	Default	Fixed	Why It Matters
allow-passthrough	off	on	Enables DEC 2026 synchronized output. Without it, Claude Code's rapid TUI updates cause visible screen tearing.
extended-keys	off	on	Lets TUI apps receive modifier key combos (Ctrl+Shift+key, etc.) that plain terminals swallow.
escape-time	500	0	Eliminates the half-second delay tmux adds when it sees Escape. Makes Claude Code feel instant.
set-clipboard	external	on	Enables native OSC 52 clipboard. Copy/paste works across SSH sessions and nested tmux.
history-limit	2000	250000	Claude Code generates 4,000-6,700 scroll events/sec during streaming. Default overflows in seconds.
focus-events	off	on	Lets Claude Code know when its pane gains/loses focus. Required for cursor management.
mouse	off	on	Enables mouse scrolling, pane selection, and resize.
default-terminal	screen	tmux-256color	Full 256-color and true-color support for the TUI.

Full Config Features

The full tmux.conf install includes everything above plus:

• Dark theme — Premium dark palette (cyan/purple accents on deep navy)
• Vim keybindings — hjkl navigation, vi copy mode, system clipboard
• Smart splits — | horizontal, - vertical (in current directory)
• C-a prefix — More ergonomic than the default C-b
• Vim-tmux navigator — C-hjkl switches between vim and tmux panes
• Floating popups — prefix + F for popup terminal, prefix + C-f for FZF session switcher
• Pane titles — Shows pane name and command in borders
• Layout presets — prefix + M-1/2/3 for horizontal/vertical/tiled
• True color — Terminal overrides for iTerm2, Ghostty, kitty, WezTerm, Alacritty
• Pane capture — prefix + M-s saves scrollback to file

Plugins (via TPM)

Plugin	Purpose
tmux-sensible	Sensible defaults everyone agrees on
tmux-resurrect	Persist sessions across tmux restarts
tmux-continuum	Auto-save every 15 min, auto-restore on start
tmux-yank	System clipboard integration (OSC 52)
tmux-fzf	Fuzzy finder for sessions/windows/panes

Key Bindings

Binding	Action
C-a	Prefix key
prefix + |	Split pane horizontal
prefix + -	Split pane vertical
prefix + h/j/k/l	Navigate panes
prefix + H/J/K/L	Resize panes
prefix + G	Toggle zoom on current pane
prefix + g	Display pane numbers
prefix + F	Floating popup terminal
prefix + C-f	FZF session/window switcher
prefix + S	Toggle pane sync (type in all panes)
prefix + s	Choose session from tree
prefix + N	New session
prefix + M-1	Main-horizontal layout (65/35)
prefix + M-2	Main-vertical layout (60/40)
prefix + M-3	Tiled layout (equal)
prefix + M-s	Capture current pane to file
prefix + M-a	Capture all panes to files
prefix + r	Reload config

Requirements

• tmux 3.2+ (required), 3.3+ (recommended for popup styling + passthrough)
• macOS, Linux, or WSL
• Git (for TPM plugin installation)

Recommended Terminal Emulators

All of these support true color and work well with this config:

• Ghostty (best overall compatibility)
• iTerm2 (macOS)
• kitty
• WezTerm
• Alacritty

Apple Terminal works but lacks true color support.

Uninstall

./install.sh --uninstall

This restores your backed-up ~/.tmux.conf and removes the overlay.

Shipwright Users

If you use Shipwright for Claude Code agent teams, you already have all these fixes. Shipwright's bundled tmux/tmux.conf includes everything in this repo plus agent-specific features (pane reaping, team dashboards, memory popups). Run shipwright tmux doctor to verify.

License

MIT