# Sessionizer for WezTerm

Lightweight workspace/session switcher inspired by [ThePrimeagen's tmux-sessionizer](https://github.com/ThePrimeagen/.dotfiles/blob/master/bin/.local/scripts/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

```lua
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. 🚀