WezTerm: The Ultimate Windows Terminal for Claude Code & Codex

Introduction

Claude Code, Codex, and similar CLI coding agents are gaining popularity, but running them on Windows often yields a subpar experience. After trying several terminals, the author settled on WezTerm — a GPU-accelerated terminal emulator and multiplexer written in Rust, MIT-licensed with 28k+ GitHub stars and active development. It runs on Windows 10+, macOS, Linux, FreeBSD, and NetBSD with consistent cross-platform behavior.

Key Features

GPU-accelerated rendering : true color, ligatures, colored emoji, font fallback, smooth rendering

Built-in multiplexer : pane/tab/window multiplexing, session persistence, tmux-like without tmux

Remote multiplexing domains : connect to remote mux server via SSH/TLS/Unix socket, auto-reconnect on disconnect

Built-in SSH client : native tabbed SSH, auto-reads ~/.ssh/config

Lua programmable configuration : config file is a Lua script, supports hot reload, logic and event binding

Terminal image protocols : iTerm2, Kitty, Sixel all supported, view images inline (built-in imgcat)

Installation and Configuration

On Windows, download the portable Nightly zip from https://wezterm.org/installation, extract to any directory, and add that directory to user PATH. Three key executables: wezterm-gui.exe — main terminal GUI, double-click to launch wezterm.exe — CLI entry point for wezterm cli,

wezterm connect

wezterm-mux-server.exe

— multiplexer service enabling session persistence

Configuration file on Windows is %USERPROFILE%\.wezterm.lua (create if missing). Minimal starter config:

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

return config

Changes apply instantly on save (hot reload).

Usage Examples

All examples modify only .wezterm.lua ; each example = a small config snippet + observed effect.

Default Shell to PowerShell

WezTerm defaults to cmd.exe on Windows, so PowerShell commands like ls fail. One-line fix:

config.default_prog = { 'powershell.exe', '-NoLogo' }

Use powershell.exe for built-in 5.1, or pwsh.exe if PowerShell 7+ is installed (recommended). New windows/tabs now launch PowerShell.

Default Working Directory

New windows start at C:\Users\username; set a project directory: config.default_cwd = 'D:\\developer\\workspace' Gotcha: Lua strings treat backslash as escape; writing D:\developer\workspace causes invalid escape sequence. Use double backslashes or forward slashes D:/developer/workspace. After config, new windows open directly in the workspace.

Shift+Enter for Newline

Claude Code uses Shift+Enter for newline. Newer WezTerm versions support it natively; if Shift+Enter still submits, add a key binding:

config.keys = {
  { key = 'Enter', mods = 'SHIFT', action = wezterm.action.SendString '
' },
}

Multi-line prompts now work. Note: paste in WezTerm is Ctrl+Shift+V (not Ctrl+V). Rebinding Ctrl+V is possible but breaks Ctrl+C/V passthrough to TUI apps.

Font and Color Scheme

For long agent sessions, font and theme matter:

config.font = wezterm.font('JetBrains Mono')
config.font_size = 14.0
config.color_scheme = 'Catppuccin Mocha'

WezTerm bundles 700+ themes; preview at the official Color Schemes page or run wezterm ls-colors. Further per-color overrides via config.colors; Lua logic can auto-switch themes based on system light/dark mode.

Multiplexer (Mux) Usage

WezTerm's built-in multiplexer runs processes under a background mux server, not the window — closing a window equals tmux detach. This works natively on Windows (tmux requires WSL). Enable local persistence with two lines:

config.unix_domains = {{ name = 'unix' }}
config.default_gui_startup_args = { 'connect', 'unix' }

Restart WezTerm, then test: give Claude a 60-second countdown task via PowerShell:

powershell -NoLogo -Command '1..60 | ForEach-Object { Write-Host "tick $_"; Start-Sleep 1 }'

Close the WezTerm window. In an external PowerShell, run wezterm cli list — the Claude pane is still alive (process not dead, just unattached).

Reopen WezTerm — session restores exactly, task completed, Claude replied "任务完成". The background mux server persists until explicitly killed:

taskkill /IM wezterm-mux-server.exe /F

Split-Screen Panes

Typical AI agent workflow: agent works in one pane, you monitor logs/tests in another. Native keybindings:

Split horizontally (left/right) : Ctrl+Shift+Alt+% Split vertically (top/bottom) : Ctrl+Shift+Alt+" Navigate between panes : Ctrl+Shift+Arrow Resize pane : Ctrl+Shift+Alt+Arrow Zoom pane (toggle) : Ctrl+Shift+Z Example layout: left pane runs Claude Code, Ctrl+Shift+Alt+% splits right pane for dev server logs. Add bottom pane with Ctrl+Shift+Alt+" for tests. Zoom with Ctrl+Shift+Z to read long output. Close unused pane with exit.

Comparison with Windows Terminal

Windows Terminal is solid, well-integrated, and zero-config for daily use. But for AI agent workflows, key gaps appear:

Platform : Windows Terminal — Windows only; WezTerm — Windows / macOS / Linux

Configuration : Windows Terminal — settings.json + GUI; WezTerm — Lua script, programmable, hot reload

Session reuse : Windows Terminal — tabs/panes only, lost on window close; WezTerm — built-in multiplexer, session persistence

Remote sessions : Windows Terminal — relies on external SSH; WezTerm — mux server auto-reconnect, state restore

Terminal images : Windows Terminal — not supported; WezTerm — iTerm2 / Kitty / Sixel

Font rendering : Windows Terminal — system native renderer; WezTerm — FreeType cross-platform, excellent ligatures

Clear scrollback : Windows Terminal — no default shortcut, manual; WezTerm — Ctrl+Shift+K one-key clear

Summary: Windows Terminal wins on convenience and integration; WezTerm wins on multiplexing, remote support, and programmability — the three features most critical for Claude Code/Codex.

Conclusion

WezTerm bundles terminal multiplexing, session persistence, and programmable configuration, directly addressing the pain points of running Claude Code/Codex on Windows: newline handling works, closing windows no longer kills sessions, split-screen monitoring needs no external tmux.

Trade-off: not zero-config like Windows Terminal; requires Lua configuration time and a few small pitfalls. But config is written once, lasts years, ports across machines and platforms — a worthwhile investment for heavy users. The same setup applies to Codex CLI and similar tools; switching agents doesn't require switching terminals.

If you run AI coding agents on Windows and find the terminal experience lacking, install WezTerm and try it for a week — you likely won't go back.

Project Repository

https://github.com/wezterm/wezterm