A wezterm sessions plugin

In this article I'll introduce you WezTerm Sessions, a new WezTerm sessions plugin.

So I was searching for a session manager (similar to tmux) for WezTerm. WezTerm is a powerful terminal emulator with many features and is highly configurable using Lua scripting, much like NeoVim.

I found several existing solutions, but none of them worked well for me. The most comprehensive one, resurrect.wezterm had issues — it randomly messed up my terminal layout and occasionally caused my tab bar to disappear.

For this reason I decided to fork WezTerm Session Manager by Daniel Copper adding some functionalities that were left unimplemented. Eventually, I refactored the entire codebase and added even more features, so I decided to rename the project. And here we are.

Before listing the features of this plugin, let me clarify one thing: I am a Linux-only user. I haven't tested, nor do I plan to test, new features on Windows or macOS. If anyone is willing to contribute in that regard, it would be much appreciated.

Features

• Save a workspace state – The state (windows, tabs, panes, and foreground processes) is stored in a JSON file so it can be recovered later. Foreground process detection works well for my use cases, but it may not be perfect.
• Restore a session state – When activating a workspace, you can attempt to restore its saved state.
• Load a session state – You can switch to a workspace and restore it in one step, selecting the workspace via fuzzy search.
• Delete a session state – Fuzzy search for a saved session and delete it.
• Edit a session state – Fuzzy search for a workspace state and open it in your preferred editor ($EDITOR) for modifications. This can be useful for tweaking the tty key, which represents the command to be executed. If the foreground process wasn’t detected correctly during saving, you can fix it manually.

Installation

Add the following to your WezTerm configuration:

 local sessions = wezterm.plugin.require("https://github.com/abidibo/wezterm-sessions")
 sessions.apply_to_config(config) -- optional, this adds default keybindings

The second line is optional and unnecessary if you prefer to set your own keybindings.

Configuration

You can define your own keybindings (the following are the defaults):

config.keys = {
    {
        key = 's',
        mods = 'ALT',
        action = act({ EmitEvent = "save_session" }),
    },
    {
        key = 'l',
        mods = 'ALT',
        action = act({ EmitEvent = "load_session" }),
    },
    {
        key = 'r',
        mods = 'ALT',
        action = act({ EmitEvent = "restore_session" }),
    },
    {
        key = 'd',
        mods = 'CTRL|SHIFT',
        action = act({ EmitEvent = "delete_session" }),
    },
    {
        key = 'e',
        mods = 'CTRL|SHIFT',
        action = act({ EmitEvent = "edit_session" }),
    },
}

in order to use the restore functionality may be useful to easily rename the current workspace or create a new namespace with a custom name, so for example you can add two keybindings like the following:

-- Rename current workspace
{
    key = '$',
    mods = 'CTRL|SHIFT',
    action = act.PromptInputLine {
        description = 'Enter new workspace name',
        action = wezterm.action_callback(
            function(window, pane, line)
                if line then
                    wezterm.mux.rename_workspace(wezterm.mux.get_active_workspace(), line)
                end
            end
        ),
    },
},
-- Prompt for a name to use for a new workspace and switch to it.
{
    key = 'w',
    mods = 'CTRL|SHIFT',
    action = act.PromptInputLine {
        description = wezterm.format {
            { Attribute = { Intensity = 'Bold' } },
            { Foreground = { AnsiColor = 'Fuchsia' } },
            { Text = 'Enter name for new workspace' },
        },
        action = wezterm.action_callback(function(window, pane, line)
            -- line will be `nil` if they hit escape without entering anything
            -- An empty string if they just hit enter
            -- Or the actual line of text they wrote
            if line then
                window:perform_action(
                    act.SwitchToWorkspace {
                        name = line,
                    },
                    pane
                )
            end
        end),
    },
},

Events

WezTerm Sessions triggers several events that you can use to react and perform actions when something happens. Each available action emits a start and end event:

• wezterm-sessions.save.start(file_path)
• wezterm-sessions.save.end(file_path, res)
• wezterm-sessions.load.start(workspace_name)
• wezterm-sessions.load.end(workspace_name)
• wezterm-sessions.restore.start(workspace_name)
• wezterm-sessions.restore.end(workspace_name)
• wezterm-sessions.delete.start(file_path)
• wezterm-sessions.delete.end(file_path, res)
• wezterm-sessions.edit.start(file_path, editor)

Limitations

This plugin works well in my scenario, but there are a few caveats:

• As mentioned, it has not been tested on Windows or macOS. Additionally, on Windows, the foreground process of a pane is not detected.

• Remote sessions can be tricky. Before restoring or load a session you have to connect to your host:
  

  wezterm connect SSHMUX:hostname
  

  Also foreground processes are not detected, but you can use the edit action to fix it. Maybe there are other issues with remote session I'm not aware of, because I barely use it.

• The plugin should be able to restore even complex pane layouts, but who knows.

• The current active tab/pane is not restored at the moment, not difficult to implement, but it's a feature I'm really not missing at the moment.

Conclusions

WezTerm Sessions is a WezTerm plugin that adds session (workspace) management to your favorite terminal multiplexer. It is designed to work well on Linux (and hopefully macOS) but does not support Windows. Contributions to improve Windows compatibility are welcome.

In my use cases, it works pretty well, restoring complex layouts with foreground processes while allowing you to save, restore, load, delete, and edit states easily.