Sessionizer for WezTerm

Lightweight workspace/session switcher inspired by ThePrimeagen's tmux-sessionizer. It scans your project directories, remembers recent workspaces, and lets you jump between them with fuzzy search inside WezTerm.

Features

• Quick Access history: recently opened workspaces bubble to the top with a configurable cap.
• Async directory scans: project discovery runs in the background so the UI never blocks.
• Glob project roots: project path entries support shell-style globs (for example ~/src/*) and expand to all matching directories.
• Safe defaults: configuration is validated, labels are sanitized, and the history file lives wherever you choose.
• Notifications: human-friendly toasts (or log fallbacks) when scans fail or no projects are found.

Installation

local wezterm = require "wezterm"
local sessionizer = wezterm.plugin.require(
  "https://github.com/jfaeys/sessionizer.wezterm"
)

local config = wezterm.config_builder and wezterm.config_builder() or {}

sessionizer.apply_to_config(config, {
  key = "F",
  mods = "LEADER",
  add_to_launch_menu = true,
  projects = {
    { path = "~/personal", max_depth = 3 },
    { path = "~/work", max_depth = 2 },
  },
  history_file = "~/.local/share/sessionizer-history.txt",
  history_max_entries = 8,
})

return config

Configuration Reference

All options are optional; reasonable defaults live in plugins/sessionizer/src/config.lua.

Option	Description
key / mods	Key binding that opens the sessionizer InputSelector.
add_to_launch_menu	When true, cached projects are added to the wezterm launch menu.
projects	Array of strings or { path, max_depth } tables describing directories to scan. Relative paths expand relative to $HOME.
exclude_dirs	Directory names to skip while scanning (see plugins/sessionizer/src/state.lua).
default_depth	Fallback depth when a project entry omits max_depth.
history_file	Location of the plain-text history log. Can live outside $HOME if desired.
history_max_entries	Number of Quick Access entries surfaced and persisted.
warmup	When true (default), a background scan is started after config load to make first open faster. Set to false for fastest startup.
warmup_delay_ms	Delay (milliseconds) before starting warmup scan. Useful to keep WezTerm startup snappy while still preloading results.

Project roots and wildcards

projects[*].path supports glob patterns like *, ?, and character classes (for example ~/src/* or ~/work/**/repos). If a glob matches multiple paths, sessionizer scans each match.

max_depth accepts a number, -1 (unlimited), or "*" (treated as a very large depth).

Usage

Press the configured key combo (e.g. LEADER + F) to open the sessionizer. Fuzzy search through the list of discovered projects. Recently opened projects show a Quick Access: prefix for fast navigation.

Launch-menu entries (when enabled) spawn new wezterm windows directly into the chosen project directory.

Development Notes

• Directory scanning relies on fd when available, otherwise falls back to find/PowerShell.
• fd availability is detected via wezterm.run_child_process and cached (avoids spawning a shell on each invocation).
• Caches are deep-copied to prevent mutation across calls.
• Workspace/project caches are invalidated automatically when the config changes (based on a fingerprint of projects, exclude_dirs, and default_depth).
• A built-in profiler can log scan timings when profiler_enabled = true (see plugins/sessionizer/src/state.lua). It logs per-base scan_base <path> and overall workspace_scan durations.
• When profiling is enabled, extra diagnostic metrics are logged:
  • Per-base: cache_hit, backend (fd/find/PowerShell), glob-expanded path count, raw output line count, directory count, and skipped control-character paths.
  • Overall: number of bases scanned, total directories returned (before dedupe), and unique directory count.
• All user-facing errors route through plugins/sessionizer/src/notify.lua, so the plugin stays compatible with different wezterm builds.

Contributions and suggestions are welcome—keep the footprint small and the workflow fast. 🚀