A fork of WezTerm
wsb-wezterm
wsb-wezterm is a fork of WezTerm. WezTerm is Wez Furlong's work, and the fork claims no part of it: it keeps WezTerm's code, licence and copyright, goes by names of its own so that it never takes the place of a WezTerm installed beside it, and changes what is listed below.
What it is
wsb-wezterm goes by its own names: its programs are wsb-wezterm, wsb-wezterm-gui and
wsb-wezterm-mux-server, its configuration is wsb-wezterm.lua, its Lua module is
require 'wsb-wezterm', and its application id is com.bahramj.wsb-wezterm. WezTerm and the
fork keep their configuration and state apart, so both can be installed on one machine.
Several of the fork’s changes change the multiplexer protocol: a GUI, a server and
wsb-wezterm cli talking to one another are all built from the fork.
What the fork changes
Everything else is WezTerm's. The list is the fork's own, from the section Changes from WezTerm of its README.
Updates
-
wsb-wezterm checks for no updates. WezTerm asks GitHub once a day for its newest release and offers to download it; a wsb-wezterm build is installed by whoever built it, so it asks nothing, and the
check_for_updates,check_for_updates_interval_secondsandshow_update_windowoptions are gone. The Help menu’s documentation entry opens this fork’s documentation.
Tabs
- Drag tabs to reorder them. Drag a tab along the tab bar with the left mouse button. From wezterm#6527 by @Jefffrey, and wezterm#7926 by @jayjohnston, which redraws the tab bar during the drag and adds a floating preview to the fancy tab bar.
-
Tab widths that fit the bar. When the retro tab bar’s titles do not all fit, a title shorter than an even share keeps its full width, and the room it leaves goes to the longer titles, instead of every tab being cut to an even share (
wezterm-gui/src/tabbar.rs,tab_widths). -
Right-clicking a tab no longer opens the tab navigator. It opens the context menu instead (below).
ShowTabNavigatoris still available as a key assignment.
Tab and window variables
-
Named values on tabs and windows that only programs set.
wsb-wezterm cli set-tab-var NAME VALUEandwsb-wezterm cli set-window-var NAME VALUE(or--unset NAME), andtab:set_var()/window:set_var()in Lua, store values a program recognizes a tab or window by later.wsb-wezterm cli list --format jsonreports them astab_varsandwindow_vars, and Lua reads them withget_vars(). Unlike titles, which any program in a pane can change with an escape sequence, nothing running in the panes can touch them. A multiplexer server’s values are mirrored by every GUI attached to it, and a value a GUI sets on a server’s tab or window is set on the server. This changes the multiplexer protocol.
Window placement and zoom in Lua
-
What a configuration needs to give a new window the placement and zoom an earlier one had, which wsb-wezterm keeps only while a window is open:
-
window:get_position()reports the top left of the window’s content area, in the coordinateswindow:set_position()takes, so moving a window to its reported position leaves it where it is. On Wayland, which tells applications nothing of where their windows are, it returnsnil(docs). -
window:get_dimensions()also reportsis_maximized(docs). -
window:get_font_scale()andwindow:set_font_scale(scale)read and set the zoom that IncreaseFontSize, DecreaseFontSize and ResetFontSize change (docs, docs). -
window:get_content_size()andwindow:set_content_size(width, height)read and set the size of the window’s content area in the units the windowing system keeps it in while the window moves between screens: points on macOS, logical pixels on Wayland, and pixels on X11 and Windows. Unlikeget_dimensions()’s pixels, which double on a Retina display, a size read on one screen gives a window the same size on every other.set_content_sizeconverts it for the screen the window is on when it applies, after aset_positionasked for before it, and keeps the content area’s top left where it is (docs, docs). - A window applies the changes Lua asks of it,
set_inner_size,set_font_scale,set_position,maximize,restoreandtoggle_fullscreen, in the order asked. Before, a move or a maximize went straight to the window and could overtake a resize asked for first.
-
-
On X11 a window declares static gravity in its size hints, the meaning
set_positiongives a position: where the content area goes, not the frame the window manager draws around it. The window manager reads a window’s position by the window’s gravity whenever it configures it; declaring none, a window placed withset_positionwas placed by its frame, a title bar lower, the next time it was resized or restored from maximized (Openbox does this).
Window size
-
A window is no larger than its screen.
window:set_inner_size(),window:set_content_size(), and wsb-wezterm’s own resizes (such as zooming withadjust_window_size_when_changing_font_size) give a window at most the visible area of its screen, as the windowing system limits a resize by the user: the screen less the menu bar and the Dock on macOS, less the taskbar on Windows, the bounds the compositor suggests on Wayland, and the whole screen on X11, which tells windows nothing of panels. Before, a size larger than the screen was applied as asked (docs). -
A window larger than the GPU can draw is not painted, and wsb-wezterm logs an error, rather than aborting. The OpenGL renderer panicked on a viewport larger than
GL_MAX_VIEWPORT_DIMS(“Viewport dimensions are too large”), and WebGPU on a surface larger than its largest texture; on macOS the panic happened where it cannot unwind, which aborts the process. Such a window now stays unpainted until it is resized to a size the GPU can draw.
Context menu
-
A right-click menu, drawn by wsb-wezterm, the same on every platform.
- In a terminal: Copy (greyed out without a selection), Paste, Split Right, Split Down, Close Pane, New Tab, and Command Palette, with their shortcuts.
- On the tab bar: New Tab, Close Tab (the tab clicked), Minimize, Maximize/Restore, and Close Window.
- It uses the command palette’s font and colours, and is navigated with the mouse or the arrow keys, Enter, and Escape.
- A program that tracks the mouse still gets the right-click; Shift+right-click always opens the menu.
- It is the new
ShowContextMenukey assignment, bound to a right-click by default (docs).
Wayland
- A window frame on desktops that leave decorations to the application, such as GNOME. WezTerm draws its own title bar and borders when the compositor refuses server-side decorations, rather than showing no frame at all. Dragging an empty part of the tab bar moves the window. From wezterm#8145 by @AlexKichkailo.
- That frame is counted in the window geometry. The size the compositor suggests includes the frame, and the geometry wsb-wezterm declares now does too. Before, resizing from a border left the terminal smaller than the window and stopped following the pointer.
- Resize cursors on the frame’s borders and corners while hovering them, not only once a drag has begun.
- A click on the title bar stays on the title bar. Clicking the frame of a window that did not have the keyboard selected the tab under the click as well: the keyboard entering the window replaced the surface pointer events were sent to, so the press went to the terminal at the title bar’s coordinates, which are the tab bar’s. Each pointer event now goes to the surface it arrived on.
macOS
- The title bar shows the terminal’s background, not the desktop. An opaque window’s background is now the color scheme’s background color rather than clear. Where macOS draws the title bar translucent, it showed whatever was behind the window, leaving only the title and the window buttons visible.
Arranging panes
-
A tab’s panes can be arranged freely through
wsb-wezterm cliand the multiplexer protocol, so a program, a web page or a Claude Code session can lay out the tab it works in (docs):-
get-layoutprints a tab’s tree of splits as JSON: each pane’s place and size, its title, working directory, foreground program and terminal device, and which pane is focused and zoomed (docs). -
set-layoutgives a tab a whole layout in one step, from a JSON tree of splits whose sizes are cells or percentages and whose panes are the tab’s, panes moved in from other tabs, or new ones (docs). -
resize-splitsets a split’s size in cells, as dragging its divider does (docs);swap-panesswaps two panes, in one tab or two (docs);send-keyspresses keys in a pane, such asCTRL+c(docs). -
relay --tab-of-pane IDrelays every pane of a tab and the tab’s layout over one connection, following the pane from tab to tab (docs). -
cli list --format jsonreports each pane’sforeground_process_name.
-
-
Every client hears of every change to a tab’s layout. The multiplexer sends
TabLayoutChanged(WezTerm’sTabResized) whenever a tab’s panes, their places or sizes, the focused pane or the zoomed pane change. WezTerm sent it only for resizes, so a split, a closed pane, a swap or a focus change made by one client reached another only when something else made it re-sync. This changes the multiplexer protocol. -
adjust-pane-size --pane-id IDmoves the divider of that pane. It moved the divider of the tab’s focused pane, whichever pane was named. -
A tab is resized as a whole, by the multiplexer. A client resizing a tab sends the tab’s new size in one request (
ResizeTab), and the multiplexer shares it out among the panes by the tab’s layout and tells every client the new layout. A GUI window’s resize, a divider dragged in a GUI andrelay --tab-of-paneall ask the multiplexer this way; a client’s mirror of a tab never asks a size for each of its panes. WezTerm’s GUI resized a tab pane by pane, one request each, and the multiplexer rebuilt each split’s size from its panes’ sizes: between those requests, or for good when the client stopped part way, the tab’s tree did not add up. A pane is resized on its own only when it is alone in its tab (relay --pane-id ID --sized-by-input); in a tab with others it is refused, naming the tab, its panes and that the tab’s layout sizes them.resize-tabsizes a tab from the command line (docs). This changes the multiplexer protocol. -
A desktop window sizes the tabs of the workspace it shows, and only another window competes with it. A GUI tells the multiplexer the workspace it shows, at each connection and whenever it switches, and
list-clientslists it. A resize asked by any other client, a relay or a command, of a tab in a workspace a GUI shows is refused, leaving the tab as the window sized it, and the refusal names the rule and each window by its user, machine and process.get-layoutsays the same for each tab, insized_by_window. A GUI attached but showing another workspace does not stop it. - Moving a divider resizes the panes nested beyond it. The panes nearest the divider give or take the cells first, and none goes below one cell. WezTerm kept the first pane of a nested split at its size, so dragging a divider into a nested split shrank the pane beyond it to nothing and pushed it past the edge of the tab.
-
A split with no room is refused before any pane is made or moved, naming the sizes.
split-panechecks that both parts and the divider fit before it starts a program or takes a--move-pane-idpane out of its tab; a pane moved within its own tab is measured for on the tab without it. WezTerm took the moved pane out of its tab, or started the new program, and only then found “No space for split!”: the pane’s program ran on in no tab, out of reach of the multiplexer and shown nowhere (docs).
Relaying a pane
-
wsb-wezterm cli relay --pane-id IDlets another program show a pane and type into it: a terminal emulator in a web page, for instance. The relay attaches to the multiplexer as a GUI does and writes the pane’s screen as escape sequences, a full paint and then only what changed, one JSON event per line on stdout. It reads keys, text, paste and mouse events on stdin, and the multiplexer encodes them with the modes of the terminal in the pane, so the program in it receives what a keyboard would send. It never resizes the pane unless started with--sized-by-input, and never takes focus. Scrollback, title, clipboard (OSC 52), bell and the pane’s colors come through as events too (docs). -
Clients say what they are for. A client attaching to a multiplexer registers as a
gui, arelay, or a short-livedcommand, andwsb-wezterm cli list-clientsshows it, so a program can tell whether a GUI is showing a multiplexer’s windows. A relay, which shows no windows, also leaves the panes’ colors to the GUIs, where a GUI tells the server the colors it uses for every pane. -
Each cell’s grapheme stays in its cell. A program can write graphemes in cells of their own that, read one after another, make one: an emoji and a skin tone modifier, two regional indicators, a letter and a combining mark. A surface’s changes (
wezterm-surface’sdiff_linesand the rest, which the relay writes its escapes from) place such a cell with an explicit cursor position, so the terminal reading them draws each where the pane holds it, rather than joining the two in the cells of one and drawing the rest of the line early. -
A key is turned into terminal input in one place (
termwiz::input::KeyInput), which the GUI and the relay share. -
A multiplexer with no domain of its own makes no ssh-agent link.
wsb-wezterm cli proxyand the relay run no programs that would use one, and each run used to leave anagent.PIDlink behind in the runtime directory.
Multiplexer clients
These affect a window attached to a mux server, such as with wsb-wezterm connect:
- A re-sync takes the server’s tab sizes without sending them back. A client re-syncs whenever the server reports a change to a tab’s layout, and used to send the size it had just been told back to the server as a new request. While the window was resized, tabs bounced between sizes, with the programs in them redrawing at each, and could be left at a stale size.
- A pane’s resizes are sent one at a time, the latest size last. Before, each one was sent on its own, unordered, and an earlier size could be the last one applied.
- Closing a window closes its tabs. Closing a window whose tabs a server holds kills those tabs in the server, as closing each tab does. Before, it detached the window from the server’s whole domain instead: every other window of that server disappeared with it, and the programs in all of them, the closed window’s included, ran on. Quitting wsb-wezterm still leaves a server’s programs running. A window wsb-wezterm fails to create still detaches its domain, so a failure ends no programs.
Several of these change the multiplexer protocol (codec version 50): GUIs, servers and wsb-wezterm cli must be built from this fork alike.
Install
No release of wsb-wezterm is published yet. It is built from its source.
-
Building from source
What a build needs, and how to build and run it.
The build instructions
Documentation
Source and licence
- Upstream
- wezterm/wezterm, WezTerm by Wez Furlong
- Source
- jowharshamshiri/wsb-wezterm