Alacritty + tmux: Ghostty-like keyboard shortcuts (Cmd+T, Cmd+D, Cmd+1-9, etc.)

Alacritty + tmux.md

Alacritty + tmux: Ghostty-like Keyboard Shortcuts

This configuration gives you Ghostty-style keyboard shortcuts (Cmd+D, Cmd+T, etc.) in Alacritty + tmux, providing a consistent terminal experience across different setups.

Why Use This?

• Consistent shortcuts: Same muscle memory whether using Ghostty, iTerm2, or Alacritty+tmux
• tmux benefits: Session persistence, remote pairing, detach/reattach, scriptable layouts
• Works everywhere: tmux runs on any server, so your workflow travels with you

Quick Start

1. Copy alacritty.toml to ~/.config/alacritty/alacritty.toml
2. Copy tmux.conf to ~/.tmux.conf
3. Restart Alacritty
4. Reload tmux: tmux source-file ~/.tmux.conf

Keyboard Shortcuts

Shortcut	Action
Cmd+T	New tab (tmux window)
Cmd+1-9	Switch to tab 1-9
Cmd+D	Split pane right (horizontal)
Cmd+Shift+D	Split pane down (vertical)
Cmd+W	Close current pane
Cmd+Arrow	Navigate between panes
Cmd+N	New tmux session

Prefix-based shortcuts (Ctrl+b, then...)

Key	Action
r	Reload tmux config
|	Split right
-	Split down
h/j/k/l	Navigate panes (vim-style)
Ctrl+h/j/k/l	Resize panes
z	Toggle pane zoom

How It Works

┌─────────────────────────────────────────────────────────────┐
│  You press Cmd+T                                            │
│       ↓                                                     │
│  Alacritty sends escape sequence: \e[34;6~                  │
│       ↓                                                     │
│  tmux receives it as "User7" (custom user-defined key)      │
│       ↓                                                     │
│  tmux executes: new-window -c "#{pane_current_path}"        │
└─────────────────────────────────────────────────────────────┘

The configs use CSI (Control Sequence Introducer) codes in the F13-F20+ range to avoid conflicts with standard terminal keys.

tmux Basics

If you're new to tmux, here are the essentials:

Sessions, Windows, and Panes

• Session: A collection of windows (like a workspace)
• Window: A tab within a session
• Pane: A split within a window

Essential Commands

tmux                    # Start new session
tmux new -s myproject   # Start named session
tmux ls                 # List sessions
tmux attach -t myproject # Reattach to session
tmux kill-session -t myproject # Kill session

Detach & Reattach

Press Ctrl+b then d to detach (session keeps running in background). Use tmux attach to reattach later - everything is exactly as you left it!

Copy Mode (scrollback)

• Ctrl+b then [ - Enter copy mode
• Use arrow keys or vim keys to scroll
• q to exit copy mode

Customization

Change the prefix key

The default tmux prefix is Ctrl+b. To change it to Ctrl+a:

# Add to tmux.conf
unbind C-b
set -g prefix C-a
bind C-a send-prefix

Add status bar customization

# Add to tmux.conf
set -g status-style 'bg=#333333 fg=#ffffff'
set -g status-left '[#S] '
set -g status-right '%H:%M %d-%b'

Troubleshooting

Cmd+T opens new Alacritty window instead of tmux tab:

• Restart Alacritty completely (Cmd+Q, reopen)
• Make sure tmux config is reloaded

Keys not working after SSH:

• The Alacritty bindings only work locally
• On remote, use prefix-based shortcuts (Ctrl+b)

Test if escape sequences reach tmux:

cat -v
# Press Cmd+T, should see: ^[[34;6~

License

MIT - Use freely!

alacritty.toml

# ============================================================================
# Alacritty Configuration - Ghostty-like Shortcuts for tmux
# ============================================================================
#
# This config maps macOS Cmd+key shortcuts to escape sequences that tmux
# can interpret. This gives you Ghostty/iTerm2-style shortcuts while
# benefiting from tmux's session management.
#
# Location: ~/.config/alacritty/alacritty.toml
#
# ============================================================================

# ----------------------------------------------------------------------------
# Shell Configuration
# ----------------------------------------------------------------------------
# Auto-start tmux on launch, attaching to existing "main" session if it exists
# -A flag: attach if session exists, otherwise create new
# -s main: name the session "main"

[terminal.shell]
program = "/bin/zsh"
args = ["-l", "-c", "tmux new-session -A -s main"]

# If you prefer to start without auto-tmux, use:
# program = "/bin/zsh"
# args = ["-l"]

# ----------------------------------------------------------------------------
# Environment Variables
# ----------------------------------------------------------------------------
# TERM should match what tmux expects for proper color/key support

[env]
TERM = "xterm-256color"

# ----------------------------------------------------------------------------
# Keyboard Bindings
# ----------------------------------------------------------------------------
#
# HOW THIS WORKS:
# ===============
# Alacritty can't directly tell tmux "create a new window". Instead, we:
# 1. Map Cmd+key to send a special escape sequence (chars = "\u001b[XX;6~")
# 2. tmux is configured to recognize these sequences as "user-defined keys"
# 3. tmux then executes the appropriate action
#
# ESCAPE SEQUENCE FORMAT:
# =======================
# We use CSI (Control Sequence Introducer) codes: \e[N;M~
# - \e[ or \u001b[ = CSI prefix
# - N = key code (we use 25-44 to avoid conflicts)
# - M = modifier (6 = Ctrl+Shift in xterm terms, chosen arbitrarily)
# - ~ = terminator
#
# These codes are in the "extended function key" range (F13+) which
# aren't used by standard terminals, avoiding any conflicts.
#
# ----------------------------------------------------------------------------

[keyboard]

# ============================================================================
# PANE MANAGEMENT
# ============================================================================

# Cmd+D: Split pane horizontally (new pane appears to the RIGHT)
# Same as Ghostty/iTerm2 behavior
[[keyboard.bindings]]
key = "D"
mods = "Command"
chars = "\u001b[25;6~"

# Cmd+Shift+D: Split pane vertically (new pane appears BELOW)
# Same as Ghostty/iTerm2 behavior
[[keyboard.bindings]]
key = "D"
mods = "Command|Shift"
chars = "\u001b[26;6~"

# Cmd+W: Close the current pane
# If it's the last pane in window, closes the window too
[[keyboard.bindings]]
key = "W"
mods = "Command"
chars = "\u001b[28;6~"

# ============================================================================
# PANE NAVIGATION
# ============================================================================
# Navigate between panes using Cmd+Arrow keys

# Cmd+Left: Move to pane on the left
[[keyboard.bindings]]
key = "Left"
mods = "Command"
chars = "\u001b[29;6~"

# Cmd+Right: Move to pane on the right
[[keyboard.bindings]]
key = "Right"
mods = "Command"
chars = "\u001b[31;6~"

# Cmd+Up: Move to pane above
[[keyboard.bindings]]
key = "Up"
mods = "Command"
chars = "\u001b[32;6~"

# Cmd+Down: Move to pane below
[[keyboard.bindings]]
key = "Down"
mods = "Command"
chars = "\u001b[33;6~"

# ============================================================================
# WINDOW (TAB) MANAGEMENT
# ============================================================================

# Cmd+T: Create a new window (tab)
# The new window opens in the same directory as the current pane
[[keyboard.bindings]]
key = "T"
mods = "Command"
chars = "\u001b[34;6~"

# Cmd+N: Create a new tmux session
# Sessions are independent workspaces, each with their own windows
[[keyboard.bindings]]
key = "N"
mods = "Command"
chars = "\u001b[35;6~"

# ============================================================================
# WINDOW (TAB) SWITCHING
# ============================================================================
# Switch directly to windows 1-9 using Cmd+number
# Just like browser tabs!

# Cmd+1: Switch to window 1
[[keyboard.bindings]]
key = "Key1"
mods = "Command"
chars = "\u001b[36;6~"

# Cmd+2: Switch to window 2
[[keyboard.bindings]]
key = "Key2"
mods = "Command"
chars = "\u001b[37;6~"

# Cmd+3: Switch to window 3
[[keyboard.bindings]]
key = "Key3"
mods = "Command"
chars = "\u001b[38;6~"

# Cmd+4: Switch to window 4
[[keyboard.bindings]]
key = "Key4"
mods = "Command"
chars = "\u001b[39;6~"

# Cmd+5: Switch to window 5
[[keyboard.bindings]]
key = "Key5"
mods = "Command"
chars = "\u001b[40;6~"

# Cmd+6: Switch to window 6
[[keyboard.bindings]]
key = "Key6"
mods = "Command"
chars = "\u001b[41;6~"

# Cmd+7: Switch to window 7
[[keyboard.bindings]]
key = "Key7"
mods = "Command"
chars = "\u001b[42;6~"

# Cmd+8: Switch to window 8
[[keyboard.bindings]]
key = "Key8"
mods = "Command"
chars = "\u001b[43;6~"

# Cmd+9: Switch to window 9
[[keyboard.bindings]]
key = "Key9"
mods = "Command"
chars = "\u001b[44;6~"

# ============================================================================
# ARROW KEY FIXES
# ============================================================================
# Explicit standard sequences for arrow keys to ensure compatibility
# Some terminal/tmux combinations need these to be explicitly defined

[[keyboard.bindings]]
key = "Right"
mods = "None"
chars = "\u001b[C"

[[keyboard.bindings]]
key = "Left"
mods = "None"
chars = "\u001b[D"

[[keyboard.bindings]]
key = "Up"
mods = "None"
chars = "\u001b[A"

[[keyboard.bindings]]
key = "Down"
mods = "None"
chars = "\u001b[B"

# ============================================================================
# DELETE KEY FIXES
# ============================================================================
# Ensure Delete and Backspace work correctly

# Forward delete key
[[keyboard.bindings]]
key = "Delete"
mods = "None"
chars = "\u001b[3~"

# Backspace key
[[keyboard.bindings]]
key = "Back"
mods = "None"
chars = "\u007f"

tmux.conf

# ============================================================================
# tmux Configuration - Ghostty-like Keybindings
# ============================================================================
#
# This config works with the companion Alacritty config to provide
# Ghostty/iTerm2-style keyboard shortcuts via escape sequences.
#
# Location: ~/.tmux.conf
#
# After editing, reload with:
#   tmux source-file ~/.tmux.conf
# Or press: Ctrl+b then r (if using this config)
#
# ============================================================================

# ============================================================================
# GENERAL SETTINGS
# ============================================================================

# Use zsh as the default shell
# Change to /bin/bash or /usr/bin/fish if preferred
set -g default-shell /bin/zsh

# Enable mouse support
# - Click to select pane
# - Drag to resize panes
# - Scroll to enter copy mode
set -g mouse on

# Start window and pane numbering at 1 instead of 0
# Makes Cmd+1 go to the first window (more intuitive)
set -g base-index 1
setw -g pane-base-index 1

# Renumber windows when one is closed
# Prevents gaps like: 1, 2, 4, 5 after closing window 3
set -g renumber-windows on

# ============================================================================
# TERMINAL & COLOR SETTINGS
# ============================================================================

# Set TERM for proper color support
# xterm-256color provides broad compatibility
set -g default-terminal "xterm-256color"

# Enable true color (24-bit RGB) for terminals that support it
# This makes colors in vim, neovim, and other apps look correct
set -ag terminal-overrides ",xterm-256color:RGB"

# ============================================================================
# PERFORMANCE SETTINGS
# ============================================================================

# Reduce escape-time (default is 500ms)
# This is the time tmux waits after receiving an escape character
# Lower = faster response, but too low may cause issues with slow connections
# 10ms is a good balance for local use
set -s escape-time 10

# Increase scrollback buffer (default is 2000)
# This is how many lines you can scroll back in copy mode
set -g history-limit 50000

# ============================================================================
# USER-DEFINED KEYS (ESCAPE SEQUENCE MAPPING)
# ============================================================================
#
# HOW THIS WORKS:
# ===============
# tmux can define "user keys" that map escape sequences to named keys.
# When Alacritty sends \e[25;6~ (for example), tmux sees it as "User0".
# We then bind User0 to an action like "split-window".
#
# The escape sequences must match exactly between Alacritty and tmux!
#
# FORMAT: set -s user-keys[N] "ESCAPE_SEQUENCE"
# - N = index (0-999)
# - Use \e for escape character (same as \033 or \x1b)
#
# ============================================================================

# Pane management
set -s user-keys[0] "\e[25;6~"   # Cmd+D (split right)
set -s user-keys[1] "\e[26;6~"   # Cmd+Shift+D (split down)
set -s user-keys[2] "\e[28;6~"   # Cmd+W (close pane)

# Pane navigation
set -s user-keys[3] "\e[29;6~"   # Cmd+Left
set -s user-keys[4] "\e[31;6~"   # Cmd+Right
set -s user-keys[5] "\e[32;6~"   # Cmd+Up
set -s user-keys[6] "\e[33;6~"   # Cmd+Down

# Window/session management
set -s user-keys[7] "\e[34;6~"   # Cmd+T (new window)
set -s user-keys[8] "\e[35;6~"   # Cmd+N (new session)

# Window switching (Cmd+1 through Cmd+9)
set -s user-keys[9] "\e[36;6~"   # Cmd+1
set -s user-keys[10] "\e[37;6~"  # Cmd+2
set -s user-keys[11] "\e[38;6~"  # Cmd+3
set -s user-keys[12] "\e[39;6~"  # Cmd+4
set -s user-keys[13] "\e[40;6~"  # Cmd+5
set -s user-keys[14] "\e[41;6~"  # Cmd+6
set -s user-keys[15] "\e[42;6~"  # Cmd+7
set -s user-keys[16] "\e[43;6~"  # Cmd+8
set -s user-keys[17] "\e[44;6~"  # Cmd+9

# ============================================================================
# GHOSTTY-LIKE KEYBINDINGS (Cmd+key via Alacritty)
# ============================================================================
#
# BINDING SYNTAX:
# ===============
# bind -n UserN action
#   -n = "no prefix" (don't require Ctrl+b first)
#   UserN = the user-defined key from above
#
# SPLIT TERMINOLOGY:
# ==================
# tmux uses confusing terminology for splits:
#   split-window -h = "horizontal split" = pane appears to the RIGHT
#   split-window -v = "vertical split" = pane appears BELOW
#
# We follow Ghostty's convention:
#   Cmd+D = split right (what tmux calls "horizontal")
#   Cmd+Shift+D = split down (what tmux calls "vertical")
#
# ============================================================================

# --- Pane Splitting ---

# Cmd+D: Split right (new pane to the right of current)
# -h = horizontal split (creates panes side by side)
# -c "#{pane_current_path}" = open in same directory as current pane
bind -n User0 split-window -h -c "#{pane_current_path}"

# Cmd+Shift+D: Split down (new pane below current)
# -v = vertical split (creates panes stacked)
bind -n User1 split-window -v -c "#{pane_current_path}"

# --- Pane Management ---

# Cmd+W: Close the current pane
# If this is the last pane, it closes the window too
bind -n User2 kill-pane

# --- Pane Navigation ---

# Cmd+Arrow: Move focus between panes
bind -n User3 select-pane -L   # Cmd+Left: go left
bind -n User4 select-pane -R   # Cmd+Right: go right
bind -n User5 select-pane -U   # Cmd+Up: go up
bind -n User6 select-pane -D   # Cmd+Down: go down

# --- Window (Tab) Management ---

# Cmd+T: Create new window (like a new tab)
# Opens in the same directory as the current pane
bind -n User7 new-window -c "#{pane_current_path}"

# Cmd+N: Create new session (a whole new workspace)
# Sessions are independent and can be detached/reattached
bind -n User8 new-session

# --- Window Switching ---

# Cmd+1-9: Jump directly to window by number
# Like switching tabs in a browser
bind -n User9 select-window -t 1
bind -n User10 select-window -t 2
bind -n User11 select-window -t 3
bind -n User12 select-window -t 4
bind -n User13 select-window -t 5
bind -n User14 select-window -t 6
bind -n User15 select-window -t 7
bind -n User16 select-window -t 8
bind -n User17 select-window -t 9

# ============================================================================
# PREFIX-BASED KEYBINDINGS (Ctrl+b, then key)
# ============================================================================
#
# These work without Alacritty - useful when SSH'd to remote servers
# or using other terminal emulators.
#
# Default prefix is Ctrl+b (press Ctrl+b, release, then press the key)
#
# ============================================================================

# Reload tmux config
# Press: Ctrl+b, then r
bind r source-file ~/.tmux.conf \; display "Config reloaded!"

# --- Alternative split bindings ---
# These are mnemonically memorable:
#   | looks like a vertical divider (split right)
#   - looks like a horizontal divider (split down)

bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# --- Vim-style pane navigation ---
# Press: Ctrl+b, then h/j/k/l

bind h select-pane -L   # Left
bind j select-pane -D   # Down
bind k select-pane -U   # Up
bind l select-pane -R   # Right

# --- Pane resizing ---
# Press: Ctrl+b, then Ctrl+h/j/k/l (hold Ctrl)
# -r = repeatable (can press multiple times without prefix)

bind -r C-h resize-pane -L 5   # Shrink left by 5 cells
bind -r C-j resize-pane -D 5   # Shrink down by 5 cells
bind -r C-k resize-pane -U 5   # Grow up by 5 cells
bind -r C-l resize-pane -R 5   # Grow right by 5 cells

# --- Pane zooming ---
# Press: Ctrl+b, then z
# Toggles current pane to fill entire window (and back)
bind z resize-pane -Z

# ============================================================================
# TIPS FOR NEW USERS
# ============================================================================
#
# SESSIONS:
#   tmux                      # Start new session
#   tmux new -s projectname   # Start named session
#   tmux ls                   # List sessions
#   tmux attach -t name       # Attach to session
#   Ctrl+b d                  # Detach from session (it keeps running!)
#
# WINDOWS (tabs):
#   Ctrl+b c                  # Create new window
#   Ctrl+b n                  # Next window
#   Ctrl+b p                  # Previous window
#   Ctrl+b 1-9                # Go to window by number
#   Ctrl+b ,                  # Rename current window
#
# PANES (splits):
#   Ctrl+b %                  # Split right (default)
#   Ctrl+b "                  # Split down (default)
#   Ctrl+b x                  # Close pane (with confirmation)
#   Ctrl+b o                  # Cycle through panes
#   Ctrl+b Space              # Cycle through layouts
#
# COPY MODE (scrollback):
#   Ctrl+b [                  # Enter copy mode
#   q                         # Exit copy mode
#   Use arrow keys or vim keys (h/j/k/l) to navigate
#   Space to start selection, Enter to copy
#
# ============================================================================