Wezterm Support

[joshmedeski]

What would you like sesh to do?

Add support to allow sesh to interact directly with Wezterm's session manager.

smart_workspace_switcher.wezterm - See MLFlexer's existing wezterm plugin for inspiration

[joshmedeski]

Plan: Abstract Session Manager to Support tmux and WezTerm

Context

Sesh currently only supports tmux as its session manager backend. The goal is to make sesh backend-agnostic so it can also support WezTerm workspaces. This was already noted as a goal in the README ("make this session manager multiplexer agnostic").

The smart_workspace_switcher.wezterm plugin demonstrates that WezTerm workspaces are conceptually similar to tmux sessions -- both are named groupings of windows/tabs tied to a working directory. The plugin uses zoxide + WezTerm's Lua API to do exactly what sesh does for tmux.

Key Finding: The Fundamental Asymmetry

tmux has full CLI control -- tmux switch-client, tmux attach-session, tmux new-session all work from any terminal.

WezTerm can list workspaces and create them via CLI (wezterm cli list, wezterm cli spawn --workspace), but has no CLI command to switch workspaces. Switching requires WezTerm's Lua API (act.SwitchToWorkspace), which only runs inside WezTerm.

This means sesh cannot be a complete standalone controller for WezTerm the way it is for tmux. Instead:

Operation	tmux: sesh handles	WezTerm: sesh handles	WezTerm: Lua plugin handles
List sessions/workspaces	Yes	Yes (wezterm cli list)	No (calls sesh list --json)
List config/zoxide sources	Yes	Yes	No (calls sesh list --json)
Create new workspace	Yes	Yes (wezterm cli spawn --workspace)	Or via SwitchToWorkspace (auto-creates)
Switch to workspace	Yes	No -- impossible from CLI	Yes (SwitchToWorkspace Lua API)
Run startup commands	Yes	Yes (wezterm cli send-text)	No
Create windows/tabs	Yes	Yes (wezterm cli spawn)	No
Preview pane content	Yes	Yes (wezterm cli get-text)	No

Recommended Architecture: Parallel Backend, Not Abstract Interface

I recommend against a generic Multiplexer interface that both tmux and WezTerm implement. The semantics are too different (attach vs switch, detached sessions, $TMUX detection, etc.). Instead, add WezTerm as a parallel backend that shares the session-sourcing pipeline (config, zoxide, naming) but has its own multiplexer package, connector strategies, and startup logic.

The backend is selected by config + auto-detection.

Implementation Plan

1. Config: Add backend field to model/config.go

# sesh.toml
backend = "tmux"  # "tmux" (default) or "wezterm"

// model/config.go
type Config struct {
    Backend string `toml:"backend"` // "tmux" or "wezterm"
    // ... existing fields unchanged ...
}

Auto-detection fallback when backend = "": check $WEZTERM_PANE vs $TMUX env vars.

File: model/config.go

2. New package: wezterm/

Mirror the tmux/ package pattern. Interface + RealWezterm implementation that shells out to wezterm cli.

// wezterm/wezterm.go
type Wezterm interface {
    ListWorkspaces() ([]*model.WeztermWorkspace, error)
    SpawnWorkspace(name string, cwd string) (string, error)
    SendText(paneID int, text string) (string, error)
    GetText(paneID int) (string, error)
    IsInside() bool  // checks $WEZTERM_PANE
    ActivatePane(paneID int) (string, error)
}

Implementation details:

• ListWorkspaces(): runs wezterm cli list --format json, groups panes by workspace name
• SpawnWorkspace(): runs wezterm cli spawn --workspace <name> --cwd <path> --new-window
• SendText(): runs wezterm cli send-text --pane-id <id> -- <text>
• GetText(): runs wezterm cli get-text --pane-id <id>
• IsInside(): checks $WEZTERM_PANE env var

New files: wezterm/wezterm.go, wezterm/list.go, wezterm/spawn.go

3. New model: model/wezterm_workspace.go

type WeztermWorkspace struct {
    Name  string
    Panes []WeztermPane
}

type WeztermPane struct {
    PaneID    int
    TabID     int
    WindowID  int
    Workspace string
    Cwd       string
    Title     string
    IsActive  bool
}

New file: model/wezterm_workspace.go

4. DI wiring: seshcli/deps.go

• Add Wezterm wezterm.Wezterm to BaseDeps
• Instantiate in NewBaseDeps()
• Pass to NewLister(), NewConnector(), NewStartup(), NewPreviewer()

File: seshcli/deps.go

5. Lister: Add WezTerm source

• New file lister/wezterm.go with listWezterm(), FindWeztermWorkspace(), GetActiveWeztermWorkspace()
• Add Wezterm bool to ListOptions
• Add "wezterm" to srcStrategies map in lister/list.go
• Add "wezterm" handling to srcs() in lister/srcs.go
• Extend Lister interface with FindWeztermWorkspace(), GetActiveWeztermWorkspace()
• Add wezterm wezterm.Wezterm field to RealLister
• Update default source list in srcs() to be backend-aware (tmux backend defaults to ["tmux", "config", "tmuxinator", "zoxide"], wezterm backend defaults to ["wezterm", "config", "zoxide"])
• HideAttached logic needs to call backend-appropriate method

Files: lister/lister.go, lister/list.go, lister/srcs.go, new lister/wezterm.go

6. Connector: Add WezTerm strategies

• New file connector/wezterm.go:
  • weztermStrategy() -- checks if workspace already exists
  • connectToWezterm() -- spawns workspace + runs startup, returns workspace name
• Modify Connect() in connector/connect.go to select strategy chain based on config.Backend
• Add wezterm wezterm.Wezterm field to RealConnector

For WezTerm, connectToWezterm() cannot switch to the workspace (CLI limitation). It creates the workspace and returns the name. The WezTerm Lua plugin is responsible for the final switch.

Files: connector/connector.go, connector/connect.go, new connector/wezterm.go

7. Startup: Abstract terminal control

The startup logic (iterate windows, send commands) is identical regardless of backend. Only three operations differ: create window, send keys, focus first window.

Extract a small interface:

// startup/terminal.go
type Terminal interface {
    CreateWindow(cwd string, name string) (string, error)
    SendCommand(target string, command string) (string, error)
    FocusFirstWindow() (string, error)
}

Create TmuxTerminal and WeztermTerminal adapters. RealStartup takes a Terminal instead of tmux.Tmux.

Files: startup/startup.go, new startup/terminal.go

8. Namer: Backend-aware name conversion

namer/convert.go currently replaces . and : for tmux compatibility. WezTerm has no such restriction. Thread the backend config into the namer (it already receives model.Config):

func convertToValidName(name string, backend string) string {
    if backend == "wezterm" {
        return name
    }
    // tmux restrictions
    validName := strings.ReplaceAll(name, ".", "_")
    validName = strings.ReplaceAll(validName, ":", "_")
    return validName
}

Files: namer/convert.go, namer/namer.go (pass config.Backend)

9. CLI commands

• sesh list: Add --wezterm/-w flag
• sesh connect: --switch flag becomes a no-op for WezTerm (no attach/switch distinction). --tmuxinator flag hidden/disabled for WezTerm.
• sesh last: For WezTerm, return an error explaining this requires the Lua plugin (no workspace history via CLI). Or skip for v1.
• sesh root: Replace GetAttachedTmuxSession() with backend-appropriate call.

Files: seshcli/list.go, seshcli/connect.go, seshcli/last.go, seshcli/root.go

10. Icon + Previewer

• Add WezTerm icon to icon/icon.go
• Add WezTerm preview strategy to previewer/ using wezterm.GetText()

Files: icon/icon.go, new previewer/wezterm.go

11. Companion WezTerm Lua Plugin (separate repo)

A thin plugin that makes sesh the data source for WezTerm's workspace switching:

-- Calls sesh list --json to get unified session data
-- Presents InputSelector fuzzy finder
-- Uses SwitchToWorkspace for the actual switch (which sesh can't do from CLI)
-- Optionally calls sesh connect for startup command support

This replaces smart_workspace_switcher's built-in zoxide integration with sesh's richer config/naming/startup support.

Gaps and Limitations

1. Workspace switching -- Cannot be done from CLI. A companion WezTerm Lua plugin is mandatory for the switch step. sesh connect can create workspaces but cannot navigate to them.

2. sesh last -- WezTerm doesn't expose workspace history via CLI. Either unsupported, or the Lua plugin tracks history.

3. Tmuxinator -- Not applicable to WezTerm. Disabled when backend = "wezterm".

4. Attach vs Switch -- ConnectOpts.Switch is meaningless for WezTerm (no detached sessions). Ignored silently.

5. Preview from outside WezTerm -- wezterm cli get-text requires the WezTerm mux server. Won't work if sesh is called from a different terminal.

6. Session persistence -- tmux sessions survive terminal close. WezTerm workspaces are GUI-only and don't persist after WezTerm exits.

7. Remote/SSH -- tmux sessions can be attached from any terminal. WezTerm workspaces are local to the GUI process.

Verification

1. just test -- all existing tests pass (no regressions)
2. sesh list --wezterm -- lists WezTerm workspaces when running inside WezTerm
3. sesh list --json -- JSON output includes WezTerm workspaces with src: "wezterm"
4. sesh connect <zoxide-path> with backend = "wezterm" -- creates workspace via wezterm cli spawn
5. Auto-detection: inside WezTerm (no tmux), sesh list defaults to WezTerm sources
6. Mock generation: just mock succeeds with new interfaces

[iainsimmons]

Hey @joshmedeski ,

This is awesome! Very excited to see this in action!

So, there actually is a way to switch WezTerm workspaces, using user vars:

In my config.fish:

function wezterm-switch-workspace -d "Switch WezTerm workspace"
    set args (jq -n --arg workspace "$argv[1]" --arg cwd "$argv[2]" '{"workspace":$workspace,"cwd":$cwd}' | base64)
    printf "\033]1337;SetUserVar=%s=%s\007" switch-workspace $args
end

And in my wezterm.lua:

wezterm.on("user-var-changed", function(window, pane, name, value)
  if name == "switch-workspace" then
    local cmd_context = wezterm.json_parse(value)
    window:perform_action(
      act.SwitchToWorkspace({
        name = cmd_context.workspace,
        spawn = {
          cwd = cmd_context.cwd,
        },
      }),
      pane
    )
  end
end)

It's a little hacky, but it works. So I think you could change the fish function for some equivalent Go code (or people just create a bash/zsh/fish function, but then they need jq as a dependency as well).