79 lines
5 KiB
Markdown
79 lines
5 KiB
Markdown
# 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. 🚀
|