Today I learned I can simply check for the existence of the file /var/run/reboot-required.

Determining if a reboot is required on Linux was originally published 4 May 2026 on https://mwop.net by Matthew Weier O'Phinney.

In browsing a number of forums, I saw one recommendation to switch the BIOS to use FastBoot.

Can confirm, works!

Update

While FastBoot helps, it doesn't entirely fix the issues. What I discovered was that the server was requiring my keyboard in order to boot; I tested this by rebooting the machine without cables, and plugging in only the keyboard.

Unfortunately, there are no BIOS settings to override this behavior. I dug up an old USB dongle for a presentation pointer, plugged that in, and voilá — it boots now. I suspect any USB HID dongle will likely work.

Headless boot for Beelink EQ14 was originally published 24 February 2026 on https://mwop.net by Matthew Weier O'Phinney.

I have a private registry in my homelab. I have an internal DNS server that can resolve it when in my home network, and my machines in my home network all use that internal DNS server. Great, fantastic, just works.

Except for some reason, when running a docker buildx build --push operation, it was unable to resolve the internal name... because it was using the wrong DNS server. It was trying to resolve via the 8.8.8.8 DNS server. The Google DNS servers. Which I've not even configured as an upstream in my recursive DNS server on the local network.

My guess is that the Docker daemon falls back to Google DNS servers if the system DNS cannot be reached at any point. Clearly, it then never tests to see if the system DNS has become reachable again, so it gets stuck there.

The solution? Restart the docker service:

sudo systemctl restart docker

Once I did that, it resolved using the system DNS next time.

When docker buildx cannot resolve your container registry was originally published 11 February 2026 on https://mwop.net by Matthew Weier O'Phinney.

No, no, I did not. I wanted to delete it.

But, of course, you cannot reference such a file by name, so I had to learn a few tricks.

First off, you can list names with binary bytes using:

/bin/ls -lb

But even better, you can get the inode if you use:

/bin/ls -li

When you do, the inode is in the first column of the list for each file.

Once you know that, you can delete the file, using find:

find . -maxdepth 1 -inum <inode_id> -exec rm -i -- {} +

Removing a filename containing a null byte or binary character on Linux was originally published 6 February 2026 on https://mwop.net by Matthew Weier O'Phinney.

But a few years ago, I started noticing that my shell load times were getting worse and worse. At that time, I discovered I could easily switch to vanilla zsh with zplug managing a small number of plugins I used (nvm, fzf, and a few others). I also discovered starship, which gave me more prompt options, with faster startup times.

And yet...

I kept reading Julia Evans recommending fish. She often would note that fish just does things that other shells need plugins or customization for: decent tab completion, better history capabilities, etc.

So I took the plunge finally in the past couple weeks to give fish a try.

Configuration

First off, the switch more than halved the amount of configuration I needed to have an equivalent setup. I was able to remove a ton of configuration I had in zsh around history management, autocompletion, and overrides.

As I noted, with zsh, I was using zplug, and I had a half-dozen plugins. With fish, initially I had no plugins, but in order to get nvm running, I needed to install fisher, the de facto fish plugin manager. But that's literally the only plugin I'm now using.

I continued to use starship and fzf, which meant two lines of configuration in my fish configuration, and no changes otherwise.

And there's no lag whatsoever when starting up a shell. With zsh, even with my minimal config, I would sometimes wait a second or two for a shell to spawn. With fish, no wait.

Discoveries

One thing I've kept from oh-my-zsh is a utility called take, which does the following:

• If given a directory name, it creates it, and then enters it
• If given an archive file, it unarchives it into a directory, and then enters that directory
• If given a git repository name, it clones it, and then enters that directory

When porting this to fish, I discovered some really cool features of that shell.

First, fish will automatically autoload functions from the functions/ subdirectory of your fish configuration. So if you name the function the same as the file (e.g., functions/take.fish), it will load it on demand. This is a nice performance improvement over loading everything.

Second, fish uses a standard syntax for any block statement. Instead of sometimes needing braces, sometimes needing a keyword (which generally varies BASED on the block type - e.g. fi to end a conditional, done to end a loop), all blocks use an end keyword. This makes it far simpler to remember and less prone to errors.

Third, when defining a function, you can specify variable names to which to capture arguments. This is far easier to visually parse and use than standard posix shells, where you use positional parameters. As an example:

function takedir -a newpath
    mkdir -p $newpath && cd $newpath
end

Fourth, while you can use the notation varname=value to define variables, there's a better built-in, the set directive, which can:

• Define block-local (set -l) and function-local (set -f) variables
• Define globally-available variables (set -g)
• Define environment variables (set -x, for export) that persist to child shells

Using this, it's far easier both to ensure that a variable is scoped correctly, as well as to reason about the scope of a given variable. And those captured arguments I mentioned? Automatically scoped to the function, so they won't bleed outside of it.

(There's also a "univeral" flag, -u, which will not only set it in the current shell, at the globally available level, but make it available across any other instances, and persist it for future invocations. This seems dangerous, though!)

The combination of these meant that the take declaration took fewer lines of code, was easier to understand, and less likely to bleed state. I'll take it!

But will I stick with it?

I think so. I even put it on some servers I maintain, and it's instantly given me more and better functionality than the default shell available on each, which makes being on those servers more comfortable. Having less configuration is something I've been keeping an eye on, as more configuration means it's harder to reason about how things work, and more likely to break or fail in interesting ways when updating or upgrading.

I'll still need to keep my bash chops; provisioning scripts for containers and VMs generally have to depend on this lowest common denominator. However, having a useful out-of-the-box shell for my workstation and servers that's easy to script? I'll take it.

From zsh to fish was originally published 17 November 2025 on https://mwop.net by Matthew Weier O'Phinney.

Recently, I wanted to create launchers for different Obsidian vaults. Obsidian provides a URL schema for this: obsidian://open?vault=VaultName. The application registers the schema handler with the system, so this should open, but evidently you can no longer use "Type=Link" in your desktop files.

What I found:

• You MUST have a "Version=1.0" line; gnome-shell just ignored any of my desktop files that omitted it.
• You can use xdg-open in your Exec line to open the URL.

[Desktop Entry]
Version=1.0
Name=Notes
Icon=/usr/share/icons/hicolor/256x256/apps/obsidian.png
Comment=My Obsidian vault for notes
Categories=Office;ProjectManagement;
Type=Application
Exec=xdg-open "obsidian://open?vault=notes"

Linux desktop files and xdg-open was originally published 3 November 2025 on https://mwop.net by Matthew Weier O'Phinney.

At some point, it went away, thankfully... but after a recent release, it turned back on, and it's been a huge pain for me. There's a bug in that the mini window follows me to the initial virtual workspace, but then doesn't follow around from there, requiring me to use the workspace tools to move it to the workspace I want, and then re-maximize it, only to have to do the whole thing again if I switch screens.

The solution turns out to be relatively simple, if incredibly unintuitive.

Zoom does NOT have a GUI setting for this, for some reason. But evidently it creates the file $HOME/.config/zoomus.conf, which is where all configuration is stored.

This file is in INI format. Find the entry enableMiniWindow, and set it to false:

enableMiniWindow=false

Restart Zoom, and you're set.

Disabling the Zoom mini window on Linux was originally published 23 September 2025 on https://mwop.net by Matthew Weier O'Phinney.

However, on Linux, it's a far from ideal tool, at least under gnome-shell. (I don't know how it does on KDE or other desktop environments.) It raises the notification, but the notification never times out, even if you provide a timeout value (fourth argument to the function). This means that you have to manually dismiss the notification, which can be annoying, particularly if the notifications happen regularly.

So, I worked up my own utility.

notify.send

Since Wezterm uses Lua for configuration, configuration actually also acts as an extension mechanism. The primary wezterm Lua module itself provides a run_child_process function for spawning a system process, which allows me to call on the system notify-send utility.

As such, I wrote up the following Lua module:

# File: notify.lua
local wezterm = require 'wezterm'
local module  = {}

local function has_value (tab, val)
    for index, value in ipairs(tab) do -- luacheck: ignore 213
        if value == val then
            return true
        end
    end

    return false
end

local function notify (subject, msg, urgency)
    local allowed_urgency = { 'low', 'normal', 'critical' }
    urgency = urgency or 'normal'
    if not has_value(allowed_urgency, urgency) then
        urgency = 'normal'
    end

    wezterm.run_child_process {
        'notify-send',
        '-i',
        'org.wezfurlong.wezterm',
        '-a',
        'wezterm',
        '-u',
        urgency,
        subject,
        msg
    }
end

module.send = notify

return module

Within other configuration, when I want to send GUI notifications, I can do the following:

local notify = require './notify'

notify.send('Subject Line', 'This is the full message', 'low')

Some notes on usage:

• The urgency argument is one of 'low', 'normal', or 'critical', and defaults to 'normal'. These correspond to the same --urgency option of notify-send, with the following behavior:
  • 'low' urgency messages are collected in the notification panel, but not displayed.
  • 'normal' urgency messages display until the system timeout for notifications is met. (For me, that's 3 seconds.) After that, it disappears into the notification panel.
  • 'critical' urgency messages require manual dismissal.
• The subject argument is used for the notification subject; it's what you see without expanding the notification.
• The msg argument is the full detail you want in the notification, and is shown when you expand the notification.

notify-send has a variety of other flags which can control things like timeout, whether or not the message is transient (i.e., will never be displayed in the notification panel), application category, etc. I've found for myself that just these three items are sufficient for probably 99% of any uses cases I'll need.

Wezterm GUI Notifications was originally published 21 October 2024 on https://mwop.net by Matthew Weier O'Phinney.

Well, I've now found a better solution.

Recently, when looking for a completely unrelated gnome-shell extension, I stumbled across the Quake terminal extension. I decided to give it a try to see if it was using a built-in terminal library, or calling out to existing terminals, and was surprised to discover it was the latter... and that it found my Wezterm install!

Not only that, but it worked exactly as I would expect - it dropped in the terminal from the top, at a partial height, and hitting the hot key scrolled it back out.

Customizing the terminal

That said, I wanted to do a couple things different, and needed to experiment:

• I wanted the terminal to be partially transparent, so that I can see what's under it on the screen.
• I don't want window decorations for my dropdown terminal.
• I want to use Wezterm's multiplexer, and open in a dedicated workspace.

I'd achieved this in tdrop by writing a separate command that tdrop would invoke, and I wondered if I could do that here.

At first, I had no luck. The terminal would open, but as a regular window, and not as a dropdown.

And then I did a bit more reading, and realized what I needed to do.

I discovered that Quake Terminal looks for .desktop files where the Categories field includes TerminalEmulator. From there, the next important bit is that the WM_CLASS of the running application has to match the application ID.

In practice, this means the following:

• The .desktop file needs the name to be a valid application ID. The recommendation in the XDG spec is that this follows the TLD.HOST.APP format, and needs to be unique. I chose net.mwop.wezterm-dropdown for mine, and thus the file is named net.mwop.wezterm-dropdown.desktop.
• When invoking Wezterm, I need to specify the WM_CLASS. I can do this with the --class option to the start subcommand: wezterm start --class=net.mwop.wezterm-dropdown.

In the end, the full command I would run became:

wezterm \
  --config "window_background_opacity=0.85" \
  --config "window_decorations='NONE'" \
  start \
    --cwd . \
    --class=net.mwop.dropdown-terminal \
    --domain unix \
    --attach \
    --workspace dropdown

I specified this originally in the Exec= line of my net.mwop.wezterm-dropdown.desktop file, but I found that it would open a bare window on first execution, and only on the second and subsequent executions would it become a dropdown.

So I moved that invocation to the file $HOME/.local/bin/wezterm-dropdown, and added an exec at the front of it, and modified the desktop file to read Exec=/home/matthew/.local/bin/wezterm-dropdown. This works slightly better - the first invocation opens it as a bare window, but when you hit the hot key again, it hides it, and after that, it opens as a dropdown. I can live with this.

The final files

The wezterm-dropdown script:

#!/usr/bin/zsh
# File: $HOME/.local/bin/wezterm-dropdown
exec wezterm \
  --config "window_background_opacity=0.85" \
  --config "window_decorations='NONE'" \
  start \
    --cwd . \
    --class=net.mwop.dropdown-terminal \
    --domain unix \
    --attach \
    --workspace dropdown

The net.mwop.wezterm-dropdown.desktop file (this goes in $HOME/.local/share/applications/):

[Desktop Entry]
Name=Dropdown Terminal
Comment=Wezterm as a dropdown terminal
Keywords=shell;prompt;command;commandline;cmd;
Icon=org.wezfurlong.wezterm
StartupWMClass=org.wezfurlong.wezterm
Exec=/home/matthew/.local/bin/wezterm-dropdown
Type=Application
Categories=System;TerminalEmulator;Utility;
Terminal=false

Wezterm Dropdown in Gnome was originally published 17 September 2024 on https://mwop.net by Matthew Weier O'Phinney.

Today I'm going to detail my exploration of Wezterm, my current daily driver.

My terminal history

I used gnome-terminal for a long time. At a certain point, I learned about "Quake"-style, dropdown terminals, and realized that these would be ideal for running one-off tasks or doing quick lookups. I used Guake for a number of years, as it was very similar to gnome-terminal.

At a certain point, however, I found gnome-terminal to be a bit slow, and started looking for alternatives. I eventually landed on one I'd used in my early days using LInux: xfce4-terminal. This one was useful as it has a native dropdown mode, which meant I could use the same terminal for dropdowns as well as my main driver. It used very few resources, and "just worked."

Until it didn't. I adopted Wayland last year, as it was clear that Ubuntu 2024.04 would likely default to it, if not outright require it. And when I did, xfce4-terminal became an issue. I cannot recall if it became slow (as it had to run via the Xorg bindings), or if it outright didn't work, but I had to switch, regardless.

I tried a number of terminals, settling on Kitty. While it didn't have a dropdown mode, I was able to accomplish it via tdrop.

Now, the interesting thing is that I discovered tdrop when I was investigating new terminal alternatives, and tried out wezterm. At the time, I didn't go with wezterm, as I found the configuration confusing (I hadn't dove into Lua yet). I'll get back to wezterm later.

Tmux saves my bacon

Now, one tool I use all the time in a terminal is tmux. Tmux basically gives you windows and panes inside your terminal. On top of that, you can have different sessions, and attach to and detach from sessions independently; this allows you to attach to the same session from multiple windows, or detach from a session you're not actively working in so you can come back to it later. When you do return, you have all the windows and panes that were open previously.

Tmux is also pluggable, and I use a couple of plugins regularly:

• vim-tmux-navigator is technically a vim/nvim plugin, but it works in tandem with configuration you set it tmux itself. What it does is make it so that you can use the same key combinations to navigate between vim/nvim and tmux panes. So, let's say you have vim in a tmux pane on the left, and it has two vertical panes. If you're in the right-most vim pane, and hit the keystroke to move right, with this plugin, that moves you into the tmux pane to the right.

  This is tremendously useful, as you don't need to think about what context you're in as you move around between vim/nvim and tmux panes.

• tmux-resurrect allows you to persist sessions between tmux server invocations. In other words, if you restart your computer, the first time you start tmux, all your sessions re-appear, and each has any previous history already present. This plugin is has helped me feel confident that I won't lose track of what I was doing if I need to reboot.

What I have done for many years is setup my dropdown terminal to create or attach to a named tmux session. This means that I always have the ability to create new windows and panes as needed from my dropdown terminal, which is hugely useful.

Additionally, most times I open a terminal, I'm starting a tmux session named to reflect what I'm doing. This ensures if I need to reboot, I don't lose my place. In fact, I find myself getting upset quite often when I start working on something and only later realize I didn't start tmux, as I have to quit what I'm doing and start back up after starting tmux. And when I SSH to another server, I hate not having tmux available; I'll often use tmux locally, which, while it means I need multiple SSH sessions, it at least gives me what I need for functionality.

I depend on terminal multiplexing. It's a basic feature I absolutely need.

Learning wezterm

When I first came across wezterm, one thing I noted is that it had a built-in multiplexing. However, it was sufficiently different from tmux that I only noted it in passing.

Sometime this past winter, I became reacquainted with Wez Furlong, author of wezterm, via Mastodon, where he's fairly active. Wez used to contribute heavily to PHP, and we would cross paths at PHP conferences in the late oughts, and it was fun to see what he's been up to since — which includes creating wezterm. As such, I figured I'd try it out again.

It soon became my daily driver. While it took a bit to get it working well with tdrop, once I did, I found it was fast, unobtrusive, and "just worked".

But at the back of my head, I kept thinking, "I wonder if this could replace tmux for me?"

When I looked at what I actually use in tmux, I found that it was just these things:

_ Powerline. And, honestly, I discovered that I never actually LOOK at my powerline, other than to see what session and window I'm in. I decided that I'd be happy with minimally seeing active windows, better yet the session, and only vaguely interested in seeing anything else (CPU usage, memory usage, time, etc.).

• Scrollback per pane
• Select and copy
• "Zoom"ing a pane (taking a single pane as "fullscreen" within a window, and then restoring to the previous layout)
• vim-tmux-navigator (see the description in the previous section)
• tmux-resurrect (natch)

This is not a huge featureset, so I set out to see if I could do these things.

One note: I never did figure out how to show the current session name in the tab bar. Otherwise, I accomplished all other goals!

Lua

Wezterm, while written in Rust, manages configuration using Lua. As it turns out... Lua can be picked up very quickly if you've used basically any programming language at all. It looks a lot like JSON, but with a limited number of statements and expressions also available.

Wezterm ships with a small number of modules that allow you to configure the terminal, as well as perform a certain number of actions, from interacting with sessions, windows, and panes, to performing prompts.

Once I picked up Lua, configuring Wezterm became relatively straightforward. I'm now considering updating my nvim configuration to be entirely in Lua as well!

Take me to your Leader

Tmux and vim/nvim each have a concept of a leader character or key sequence. These allow you a bit more flexibility when creating keyboard shortcuts, as you don't need to worry about conflicts with other programs. The program "screen" (the OG terminal multiplexer) uses "Ctrl-A" as the leader, while tmux uses "Ctrl-B" by default (but most tmux users remap it to Ctrl-A). In vim, I map , as my leader character.

Wezterm allows defining a leader as well. I decided I'd use "Ctrl-A", as the plan is to replace tmux:

wezterm.config.leader = {
  key = 'a',
  mods = 'CTRL',
  timeout_milliseconds = 2000,
}

Scrollback, select, and copy

Wezterm allows scrollback in its copy mode. I setup a keybinding mimicing the backscroll/copy mode in tmux:

wezterm.config.keys = {
  {
    key = '[',
    mods = 'LEADER',
    action = wezterm.action.ActivateCopyMode,
  },
}

Interestingly, I found the copy mode in wezterm to be more predictable than in tmux!

Zooming

Sometimes I'm in a pane within a split window, and realize I need a bit more visual room. I had mapped Alt-F to this in tmux, so I did the same with wezterm.

wezterm.config.keys = {
  {
    key = 'f',
    mods = 'ALT',
    action = wezterm.action.TogglePaneZoomState,
  },
}

Windows versus Tabs

Tmux calls them windows, but wezterm calls them tabs. The idea is the same: a discrete, indexed and/or named terminal that can handle one or more panes.

Tmux puts the list of windows at the bottom by default (I think this can be configured, but I've literally only ever had them at the bottom of the screen). Wezterm puts them at the top. I wanted to switch the behavior, but could not find the setting... so I popped into the wezterm matrix room to ask. Wez responded within minutes, and pointed me to the tab_bar_at_bottom setting. (The matrix room is incredibly friendly and positive!)

wezterm.config.tab_bar_at_bottom = true

How do I create a tab? Wezterm, like most terminals, uses Ctrl-Shift-Tab, but with tmux, I would use <Leader>c, so I added that binding:

wezterm.config.keys = {
  {
    key = 'c',
    mods = 'LEADER',
    action = act.SpawnTab 'CurrentPaneDomain',
  },
}

Next, I wanted a way to move between tabs without a mouse. I mapped these the same as I did in tmux: <Leader>n for the next tab, <Leader>p for the previous:

wezterm.config.keys = {
  {
    key = 'n',
    mods = 'LEADER',
    action = wezterm.action.ActivateTabRelative(1),
  },
  {
    key = 'p',
    mods = 'LEADER',
    action = wezterm.action.ActivateTabRelative(-1),
  },
}

I like to name my windows/tabs. This helps me understand what work I'm doing in each: tests, running docker images, etc. In tmux, I use <Leader>, to do this, and this was where my first real Lua came in, as I had to define a callback with a conditional to make it happen:

wezterm.config.keys = {
  {
    key = ',',
    mods = 'LEADER',
    action = act.PromptInputLine {
      description = 'Enter new name for tab',
      action = wezterm.action_callback(
        function(window, pane, line)
          if line then
            window:active_tab():set_title(line)
          end
        end
      ),
    },
  },
}

How about switching to a specific tab? With tmux, you would do <Leader><index>, where <index> is the index of the window you want (e.g. "1" or "3"). For wezterm, I decided to use the tab navigator, which gives a dialog displaying each tab with their index; you then specify the one you want, either by navigating to it, or entering the index. Even better, you can use / to filter through them, which is handy if you have more than ten windows, as otherwise indexes only get you from 0-9!

wezterm.config.keys = {
  {
    key = 'w',
    mods = 'LEADER',
    action = act.ShowTabNavigator,
  },
}

I also want to be able to kill/close a tab without needing to type "exit"; this is particularly important if a process is stuck. Again, I went with what I knew from tmux, and used <Leader>&... and learned a valuable lesson in wezterm configuration in the process!

wezterm.config.keys = {
  -- Close tab
  {
    key = '&',
    mods = 'LEADER|SHIFT',
    action = act.CloseCurrentTab{ confirm = true },
  },
}

As it turns out, if a character requires hitting the shift key normally, such as any of the symbols above the numeric keys, or even keys like ?, <, >, the | and {/} symbols, the SHIFT mod MUST be included!

Finally, there were a smattering of other configuration settings I changed to make the behavior match my expectations, as well as to make it visually easier to parse:

-- Make it look like tabs, with better GUI controls
wezterm.config.use_fancy_tab_bar = true
-- Don't let any individual tab name take too much room
wezterm.config.tab_max_width = 32
wezterm.config.colors = {
  tab_bar = {
    active_tab = {
      -- I use a solarized dark theme; this gives a teal background to the active tab
      fg_color = '#073642'
      bg_color = '#2aa198'
    }
  }
}
-- Switch to the last active tab when I close a tab
wezterm.config.switch_to_last_active_tab_when_closing_tab = true

I really appreciate the attention to detail when naming configuration options. Once you figure out what option you need, you don't need to look up what it does!

Panes

The huge benefit that screen, and later, tmux, introduced is the ability to have multiple panes within a window. This allows you to essentially treat your terminal like you would a tiled window manager. During my years as an engineer, this allowed me to treat my CLI as an IDE: I'd have one pane open with vim/nvim, split between a test case and the source code I was modifying; another would be used to run unit tests, which also gave me the ability to scroll back and view specific error messages and traces.

So if I was going to use wezterm, I'd need to be able to split my window/tab into panes. Additionally, I would need the ability to keep a fair amount of scrollback history, be able to use my mouse when desired, etc. On top of all that, I'd want to be able to navigate seamlessly between vim/nvim panes and wezterm panes.

Let's tackle the (n)vim <-> wezterm pane issues first, as this also dictates keybindings eventually. I found wezterm.nvim, which, despite its name, interacts primarily with wezterm.

The first step of setup is to modify your shell configuration to add the following line to your shell configuation (assuming you use bash or zsh):

[ -n "$WEZTERM_PANE" ] && export NVIM_LISTEN_ADDRESS="/tmp/nvim$WEZTERM_PANE"

Once that's in place, you clone the project, and use the go language compiler to build and install it; this will install the utilitywezterm.nvim.navigator. Run which wezterm.nvim.navigator when done to find the path on your sytem where it's installed, as it will be needed to setup your wezterm configuration.

From there, you define a function in the configuration that uses that utility to determine if you're in a vim/nvim pane or in a wezterm pane, and, from there, determines what needs to be done to move in the direction requested. You then also define a number of event handlers that invoke this function, and finally some keybindings to trigger those events.

The beauty of this is that you don't need anything in your vim/nvim configuration; it just uses the default keybindings to move between panes, as wezterm now invokes them!

Now, on top of this, you can also specify some keybindings for resizing panes, which is really useful. This requires setting up some very similar functionality (a function to perform the resizing, event handlers to invoke it, and keybindings).

I bound <Ctrl>-(hjkl) for moving between windows (these are the standard vim movement mappings), and <Alt>-(hjkl) for resizing.

The full configuration for these motions is here:

-- Pull in the wezterm API
local os              = require 'os'
local wezterm         = require 'wezterm'
local act             = wezterm.action

-- This table will hold the configuration.
local config = {}

-- In newer versions of wezterm, use the config_builder which will
-- help provide clearer error messages
if wezterm.config_builder then
  config = wezterm.config_builder()
end


local move_around = function(window, pane, direction_wez, direction_nvim)
  local result = os.execute("env NVIM_LISTEN_ADDRESS=/tmp/nvim" .. pane:pane_id() .. " " .. wezterm.home_dir .. "/.local/bin/wezterm.nvim.navigator" .. " " .. direction_nvim)
  if result then
  window:perform_action(
      act({ SendString = "\x17" .. direction_nvim }),
      pane
    )
  else
    window:perform_action(
      act({ ActivatePaneDirection = direction_wez }),
      pane
    )
  end
end

wezterm.on("move-left", function(window, pane)
	move_around(window, pane, "Left", "h")
end)

wezterm.on("move-right", function(window, pane)
	move_around(window, pane, "Right", "l")
end)

wezterm.on("move-up", function(window, pane)
	move_around(window, pane, "Up", "k")
end)

wezterm.on("move-down", function(window, pane)
	move_around(window, pane, "Down", "j")
end)

local vim_resize = function(window, pane, direction_wez, direction_nvim)
	local result = os.execute(
		"env NVIM_LISTEN_ADDRESS=/tmp/nvim"
			.. pane:pane_id()
			.. " "
            .. wezterm.home_dir
			.. "/.local/bin/wezterm.nvim.navigator"
			.. " "
			.. direction_nvim
	)
	if result then
		window:perform_action(act({ SendString = "\x1b" .. direction_nvim }), pane)
	else
		window:perform_action(act({ ActivatePaneDirection = direction_wez }), pane)
	end
end

wezterm.on("resize-left", function(window, pane)
	vim_resize(window, pane, "Left", "h")
end)

wezterm.on("resize-right", function(window, pane)
	vim_resize(window, pane, "Right", "l")
end)

wezterm.on("resize-up", function(window, pane)
	vim_resize(window, pane, "Up", "k")
end)

wezterm.on("resize-down", function(window, pane)
	vim_resize(window, pane, "Down", "j")
end)

config.keys = {
    -- CTRL + (h,j,k,l) to move between panes
    {
        key = 'h',
        mods = 'CTRL',
        action = act({ EmitEvent = "move-left" }),
    },
    {
        key = 'j',
        mods = 'CTRL',
        action = act({ EmitEvent = "move-down" }),
    },
    {
        key = 'k',
        mods = 'CTRL',
        action = act({ EmitEvent = "move-up" }),
    },
    {
        key = 'l',
        mods = 'CTRL',
        action = act({ EmitEvent = "move-right" }),
    },
    -- ALT + (h,j,k,l) to resize panes
    {
        key = 'h',
        mods = 'ALT',
        action = act({ EmitEvent = "resize-left" }),
    },
    {
        key = 'j',
        mods = 'ALT',
        action = act({ EmitEvent = "resize-down" }),
    },
    {
        key = 'k',
        mods = 'ALT',
        action = act({ EmitEvent = "resize-up" }),
    },
    {
        key = 'l',
        mods = 'ALT',
        action = act({ EmitEvent = "resize-right" }),
    },
}

So this gives me movement, but how do I actually split the window into panes? For this, I've always favored <Leader>| to split into vertical panes, and <Leader>- to split into horizontal panes:

config.keys = {
  -- Vertical split
  {
    -- |
    key = '|',
    mods = 'LEADER|SHIFT',
    action = act.SplitPane {
      direction = 'Right',
      size = { Percent = 50 },
    },
  },
  -- Horizontal split
  {
    -- -
    key = '-',
    mods = 'LEADER',
    action = act.SplitPane {
      direction = 'Down',
      size = { Percent = 50 },
    },
  },
}

Sometimes I want to swap a pane with another one, because they're not positioned the way I'd like. I bound <Leader>{ to the wezterm PaneSelect action, which allows me to choose the pane I wish to swap with using an alphanumerical index:

config.keys = {
  {
    -- |
    key = '{',
    mods = 'LEADER|SHIFT',
    action = act.PaneSelect { mode = 'SwapWithActiveKeepFocus' }
  },
}

And sometimes I like to move back and forth between panes; I use <Leader>; and <Leader>; for that:

config.keys = {
  {
    key = ';',
    mods = 'LEADER',
    action = act.ActivatePaneDirection('Prev'),
  },
  {
    key = 'o',
    mods = 'LEADER',
    action = act.ActivatePaneDirection('Next'),
  },
}

With all of these in place, I'm very nearly there. Just a couple of minor settings:

config.pane_focus_follows_mouse = true
config.scrollback_lines = 5000
-- I don't really have need for padding between panes
config.window_padding = {
  left = 0,
  right = 0,
  top = 0,
  bottom = 0,
}

Sessions

Next up on my list of functionality: sessions.

As noted before, tmux sessions, paired with tmux-resurrect, have given me confidence that I won't lose work if I need to restart my computer, or if the battery dies. How can I reproduce this with wezterm?

By default, each wezterm instance defines its own workspaces, which are analogous to tmux sessions... kind of. You can create additional workspaces and switch between workspaces using a variety of tools.

However, if you want to share workspaces between wezterm instances, you need to have a mux domain running, and connect to it. A mux domain is a set of workspaces, windows, and tabs. By default, a "local" domain is created everytime you start a wezterm terminal, but you can define additional domains as well, including remote mux servers running on an SSH-accessible server or TLS-guarded remote port, or a simple unix domain.

In my case, I'm configuring a unix domain to run out of the box:

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

This tells wezterm to setup a mux server on a unix socket. It does not connect to it out of the box, but it does ensure it's running.

From there, I've created two keybindings: one for connecting to the mux server, and another for detaching from it. This approach somewhat mirrors how you use tmux: you have to start tmux to create sessions, and detaching from it will drop you back into your original shell.

config.keys = {
  -- Attach to muxer
  {
    key = 'a',
    mods = 'LEADER',
    action = act.AttachDomain 'unix',
  },

  -- Detach from muxer
  {
    key = 'd',
    mods = 'LEADER',
    action = act.DetachDomain { DomainName = 'unix' },
  },
}

With the muxer, I can create workspaces. These are analogous to tmux sessions, and are a group of windows and panes. When you start a wezterm terminal, you're in a "default" workspace. So the first thing to do is to allow renaming the workspace to reflect what I'm working on:

config.keys = {
  -- Rename current session; analagous to command in tmux
  {
    key = '$',
    mods = 'LEADER|SHIFT',
    action = act.PromptInputLine {
      description = 'Enter new name for session',
      action = wezterm.action_callback(
        function(window, pane, line)
          if line then
            mux.rename_workspace(
              window:mux_window():get_workspace(),
              line
            )
          end
        end
      ),
    },
  },
}

The above maps <Leader>$ to prompt you to rename the session.

From here, how do I switch to another workspace, or create a new one? For that, I mapped <Leader>s to show the workspace launcher; this lists available workspaces, allows you to switch between them, as well as create new workspaces:

config.keys = {
  -- Show list of workspaces
  {
    key = 's',
    mods = 'LEADER',
    action = act.ShowLauncherArgs { flags = 'WORKSPACES' },
  },
}

The workflow then looks like this:

• Start wezterm.

• If I want to be able to switch between mux workspaces on other windows, I then hit <Leader>a. This will connect to the mux server, and throw me into the default workspace.

• If I want to leave the mux session, I can hit <Leader>d, which will detach me from it, taking me back to the "Local" domain for the GUI window I'm in.

  • At this point, typing exit will close the window, as I'll have left the last pane of the last window in the workspace.

One thing that is odd about the situation: if you are in a mux session with multiple workspaces, and you exit out of the last pane of the last window of a workspace... it doesn't close the window or drop you out of the mux domain. Instead, it takes you to the last active workspace. This can be confusing at first. However, all you need to do at that point is hit <Leader>d to detach, and that will take you back to the local domain, from which you can exit normally.

Interestingly, you can use the system controls to close the window at any point (e.g., hitting the close button, or using a keybinding like <Ctrl>w or <Alt>F4). The mux server will keep the state for you. Of course, if you do this and you don't want the workspace to persist, you'll need to return to that workspace at some point and exit out of it.

Keeping things safe

Now that I have a concept of sessions, what about recovery? One of my most used features in tmux was the tmux-resurrect plugin, which allowed me to save and restore sessions (and did some background periodic saving for me). Can I do that with wezterm?

Yes, to an extent, via the wezterm-session-manager project. This is a Lua module that you add to your wezterm configuration; you clone it in the $HOME/.config/wezterm/ directory, and then import it into your configuration:

local session_manager = require 'wezterm-session-manager/session-manager'

From there, you need to register some event listeners:

wezterm.on("save_session", function(window) session_manager.save_state(window) end)
wezterm.on("load_session", function(window) session_manager.load_state(window) end)
wezterm.on("restore_session", function(window) session_manager.restore_state(window) end)

Finally, add some keybindings; I registered <Leader>S to save the session, <Leader>l to load a session (this doesn't currently work), and <Leader>R to restore from the most recent previous save point:

config.keys = {
  -- Session manager bindings
  {
    key = 's',
    mods = 'LEADER|SHIFT',
    action = act({ EmitEvent = "save_session" }),
  },
  {
    key = 'L',
    mods = 'LEADER|SHIFT',
    action = act({ EmitEvent = "load_session" }),
  },
  {
    key = 'R',
    mods = 'LEADER|SHIFT',
    action = act({ EmitEvent = "restore_session" }),
  },
}

Ready to Launch

Wezterm ships with an XDG desktop file, which works, but it will always open the same window by default. Also, I prefer to have a simpler shortcut than <Super> + type something to search for the app. As such, I usually bind <Super>t to open my terminal.

For the actual command, I use wezterm-gui start --always-new-process. This ensures that I get a new window each time, and that it's not bound to another domain or workspace at start; I can use my other keybindings to attach to a domain, rename or create new workspaces, etc.

Watch for the drop!

Update 2024-09-17

I have found a new solution for implementing a dropdown terminal via the gnome-shell Quake Terminal extension; you can read my blog post about setting up Quake Terminal with Wezterm for instructions.

#!/bin/bash
# File: $HOME/.local/bin/dropdown-terminal 
WAYLAND_DISPLAY=no \
  $HOME/.local/bin/tdrop --class=dropdown -mta \
  wezterm-gui \
    --config "window_background_opacity=0.85" \
    --config "window_decorations='NONE'" \
    start \
      --domain unix \
      --attach \
      --workspace dropdown

The full configuration

Here it is. I'm sure there's stuff I could do better, but it works.

-- Pull in the wezterm API
local os              = require 'os'
local wezterm         = require 'wezterm'
local session_manager = require 'wezterm-session-manager/session-manager'
local act             = wezterm.action
local mux             = wezterm.mux

-- --------------------------------------------------------------------
-- FUNCTIONS AND EVENT BINDINGS
-- --------------------------------------------------------------------

-- Session Manager event bindings
-- See https://github.com/danielcopper/wezterm-session-manager
wezterm.on("save_session", function(window) session_manager.save_state(window) end)
wezterm.on("load_session", function(window) session_manager.load_state(window) end)
wezterm.on("restore_session", function(window) session_manager.restore_state(window) end)

-- Wezterm <-> nvim pane navigation
-- You will need to install https://github.com/aca/wezterm.nvim
-- and ensure you export NVIM_LISTEN_ADDRESS per the README in that repo

local move_around = function(window, pane, direction_wez, direction_nvim)
    local result = os.execute("env NVIM_LISTEN_ADDRESS=/tmp/nvim" .. pane:pane_id() .. " " .. wezterm.home_dir .. "/.local/bin/wezterm.nvim.navigator" .. " " .. direction_nvim)
    if result then
		window:perform_action(
            act({ SendString = "\x17" .. direction_nvim }),
            pane
        )
    else
        window:perform_action(
            act({ ActivatePaneDirection = direction_wez }),
            pane
        )
    end
end

wezterm.on("move-left", function(window, pane)
	move_around(window, pane, "Left", "h")
end)

wezterm.on("move-right", function(window, pane)
	move_around(window, pane, "Right", "l")
end)

wezterm.on("move-up", function(window, pane)
	move_around(window, pane, "Up", "k")
end)

wezterm.on("move-down", function(window, pane)
	move_around(window, pane, "Down", "j")
end)

local vim_resize = function(window, pane, direction_wez, direction_nvim)
	local result = os.execute(
		"env NVIM_LISTEN_ADDRESS=/tmp/nvim"
			.. pane:pane_id()
			.. " "
            .. wezterm.home_dir
			.. "/.local/bin/wezterm.nvim.navigator"
			.. " "
			.. direction_nvim
	)
	if result then
		window:perform_action(act({ SendString = "\x1b" .. direction_nvim }), pane)
	else
		window:perform_action(act({ ActivatePaneDirection = direction_wez }), pane)
	end
end

wezterm.on("resize-left", function(window, pane)
	vim_resize(window, pane, "Left", "h")
end)

wezterm.on("resize-right", function(window, pane)
	vim_resize(window, pane, "Right", "l")
end)

wezterm.on("resize-up", function(window, pane)
	vim_resize(window, pane, "Up", "k")
end)

wezterm.on("resize-down", function(window, pane)
	vim_resize(window, pane, "Down", "j")
end)

-- --------------------------------------------------------------------
-- CONFIGURATION
-- --------------------------------------------------------------------

-- This table will hold the configuration.
local config = {}

-- In newer versions of wezterm, use the config_builder which will
-- help provide clearer error messages
if wezterm.config_builder then
  config = wezterm.config_builder()
end

config.adjust_window_size_when_changing_font_size = false
config.automatically_reload_config = true
config.color_scheme = 'Solarized (dark) (terminal.sexy)'
config.enable_scroll_bar = true
config.enable_wayland = true
-- config.font = wezterm.font('Hack')
config.font = wezterm.font('Monaspace Neon')
config.font_size = 12.0
config.hide_tab_bar_if_only_one_tab = true
-- The leader is similar to how tmux defines a set of keys to hit in order to
-- invoke tmux bindings. Binding to ctrl-a here to mimic tmux
config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 2000 }
config.mouse_bindings = {
    -- Open URLs with Ctrl+Click
    {
        event = { Up = { streak = 1, button = 'Left' } },
        mods = 'CTRL',
        action = act.OpenLinkAtMouseCursor,
    }
}
config.pane_focus_follows_mouse = true
config.scrollback_lines = 5000
config.use_dead_keys = false
config.warn_about_missing_glyphs = false
config.window_decorations = 'TITLE | RESIZE'
config.window_padding = {
    left = 0,
    right = 0,
    top = 0,
    bottom = 0,
}

-- Tab bar
config.use_fancy_tab_bar = true
config.tab_bar_at_bottom = true
config.switch_to_last_active_tab_when_closing_tab = true
config.tab_max_width = 32
config.colors = {
    tab_bar = {
        active_tab = {
            fg_color = '#073642',
            bg_color = '#2aa198',
        }
    }
}

-- Setup muxing by default
config.unix_domains = {
  {
    name = 'unix',
  },
}

-- Custom key bindings
config.keys = {
    -- -- Disable Alt-Enter combination (already used in tmux to split pane)
    -- {
    --     key = 'Enter',
    --     mods = 'ALT',
    --     action = act.DisableDefaultAssignment,
    -- },

    -- Copy mode
    {
        key = '[',
        mods = 'LEADER',
        action = act.ActivateCopyMode,
    },

    -- ----------------------------------------------------------------
    -- TABS
    --
    -- Where possible, I'm using the same combinations as I would in tmux
    -- ----------------------------------------------------------------

    -- Show tab navigator; similar to listing panes in tmux
    {
        key = 'w',
        mods = 'LEADER',
        action = act.ShowTabNavigator,
    },
    -- Create a tab (alternative to Ctrl-Shift-Tab)
    {
        key = 'c',
        mods = 'LEADER',
        action = act.SpawnTab 'CurrentPaneDomain',
    },
    -- Rename current tab; analagous to command in tmux
    {
        key = ',',
        mods = 'LEADER',
        action = act.PromptInputLine {
            description = 'Enter new name for tab',
            action = wezterm.action_callback(
                function(window, pane, line)
                    if line then
                        window:active_tab():set_title(line)
                    end
                end
            ),
        },
    },
    -- Move to next/previous TAB
    {
        key = 'n',
        mods = 'LEADER',
        action = act.ActivateTabRelative(1),
    },
    {
        key = 'p',
        mods = 'LEADER',
        action = act.ActivateTabRelative(-1),
    },
    -- Close tab
    {
        key = '&',
        mods = 'LEADER|SHIFT',
        action = act.CloseCurrentTab{ confirm = true },
    },

    -- ----------------------------------------------------------------
    -- PANES
    --
    -- These are great and get me most of the way to replacing tmux
    -- entirely, particularly as you can use "wezterm ssh" to ssh to another
    -- server, and still retain Wezterm as your terminal there.
    -- ----------------------------------------------------------------

    -- -- Vertical split
    {
        -- |
        key = '|',
        mods = 'LEADER|SHIFT',
        action = act.SplitPane {
            direction = 'Right',
            size = { Percent = 50 },
        },
    },
    -- Horizontal split
    {
        -- -
        key = '-',
        mods = 'LEADER',
        action = act.SplitPane {
            direction = 'Down',
            size = { Percent = 50 },
        },
    },
    -- CTRL + (h,j,k,l) to move between panes
    {
        key = 'h',
        mods = 'CTRL',
        action = act({ EmitEvent = "move-left" }),
    },
    {
        key = 'j',
        mods = 'CTRL',
        action = act({ EmitEvent = "move-down" }),
    },
    {
        key = 'k',
        mods = 'CTRL',
        action = act({ EmitEvent = "move-up" }),
    },
    {
        key = 'l',
        mods = 'CTRL',
        action = act({ EmitEvent = "move-right" }),
    },
    -- ALT + (h,j,k,l) to resize panes
    {
        key = 'h',
        mods = 'ALT',
        action = act({ EmitEvent = "resize-left" }),
    },
    {
        key = 'j',
        mods = 'ALT',
        action = act({ EmitEvent = "resize-down" }),
    },
    {
        key = 'k',
        mods = 'ALT',
        action = act({ EmitEvent = "resize-up" }),
    },
    {
        key = 'l',
        mods = 'ALT',
        action = act({ EmitEvent = "resize-right" }),
    },
    -- Close/kill active pane
    {
        key = 'x',
        mods = 'LEADER',
        action = act.CloseCurrentPane { confirm = true },
    },
    -- Swap active pane with another one
    {
        key = '{',
        mods = 'LEADER|SHIFT',
        action = act.PaneSelect { mode = "SwapWithActiveKeepFocus" },
    },
    -- Zoom current pane (toggle)
    {
        key = 'z',
        mods = 'LEADER',
        action = act.TogglePaneZoomState,
    },
    {
        key = 'f',
        mods = 'ALT',
        action = act.TogglePaneZoomState,
    },
    -- Move to next/previous pane
    {
        key = ';',
        mods = 'LEADER',
        action = act.ActivatePaneDirection('Prev'),
    },
    {
        key = 'o',
        mods = 'LEADER',
        action = act.ActivatePaneDirection('Next'),
    },

    -- ----------------------------------------------------------------
    -- Workspaces
    --
    -- These are roughly equivalent to tmux sessions.
    -- ----------------------------------------------------------------

    -- Attach to muxer
    {
        key = 'a',
        mods = 'LEADER',
        action = act.AttachDomain 'unix',
    },

    -- Detach from muxer
    {
        key = 'd',
        mods = 'LEADER',
        action = act.DetachDomain { DomainName = 'unix' },
    },

    -- Show list of workspaces
    {
        key = 's',
        mods = 'LEADER',
        action = act.ShowLauncherArgs { flags = 'WORKSPACES' },
    },
    -- Rename current session; analagous to command in tmux
    {
        key = '$',
        mods = 'LEADER|SHIFT',
        action = act.PromptInputLine {
            description = 'Enter new name for session',
            action = wezterm.action_callback(
                function(window, pane, line)
                    if line then
                        mux.rename_workspace(
                            window:mux_window():get_workspace(),
                            line
                        )
                    end
                end
            ),
        },
    },

    -- Session manager bindings
    {
        key = 's',
        mods = 'LEADER|SHIFT',
        action = act({ EmitEvent = "save_session" }),
    },
    {
        key = 'L',
        mods = 'LEADER|SHIFT',
        action = act({ EmitEvent = "load_session" }),
    },
    {
        key = 'R',
        mods = 'LEADER|SHIFT',
        action = act({ EmitEvent = "restore_session" }),
    },
}

-- and finally, return the configuration to wezterm
return config

Closing

I've been really impressed by Wezterm! One thing that's absolutely magical is that I don't ever have to think about whether or not I've started tmux; I can just start splitting the window into panes on the fly as needed. On top of that, having the configuration be a limited programming language, and one that is NOT specific to Wezterm, means that I can (a) use a skill I already have, and (b) do some limited programming of terminal behavior, which allows me to customize it for my own use cases.

Would I recommend Wezterm to others? Absolutely! One reason I was excited to try it is so I could use a terminal I could potentially port elsewhere; Wezterm works on Linux, obviously, but also Windows and Mac, making it a great cross-platform replacement for whatever native terminals you were using previously. This can be hugely useful if you switch between systems regularly, or even if you are contemplating a switch in the future and want to make your landing as soft as possible.

Thanks, Wez, for this great software, and a huge thank you to your community and contributors as well!

How I use Wezterm was originally published 4 July 2024 on https://mwop.net by Matthew Weier O'Phinney.