herdr-sesh¶
A Sesh-inspired workspace picker and session manager for Herdr.
herdr-sesh combines running Herdr workspaces, configured sessions, and
zoxide history in one searchable overlay. Selecting an item focuses its
existing workspace or creates a new one with the configured startup command,
tabs, and pane layouts.
Choose your Herdr integration¶
This repository provides a herdr-tui plugin for Herdr's terminal UI and
herdr-app mods for the desktop app. Both use the same herdr-sesh binary
and native TOML configuration.
| Capability | Herdr TUI plugin | Herdr app mods |
|---|---|---|
| Installation | Plugin installation | App mod setup |
| Open the picker | fullerzz.sesh.open-picker plugin action |
mod.open:sesh |
| Select existing remote workspaces | Unavailable | Supported for existing remote spaces |
| Track navigation outside Sesh | Automatic through plugin hooks | Requires a sesh-last layout block |
| Pane split ratios | Supported | Splits evenly; ignores ratio |
Remote workspace support is available only through the Herdr app integration, including direct CLI commands targeting the app. Configured sessions and directory entries create local workspaces in both integrations; Sesh cannot create remote workspaces from configuration.
| Sesh term | Herdr TUI term | Herdr app term |
|---|---|---|
| Session | Workspace | Space |
| Window | Tab | Tab |
| Picker | Overlay pane | Mod dialog |
The picker focuses a workspace that is already running. Selecting a configured workspace or zoxide directory creates one if it is not open. Startup commands, tabs, and pane layouts run only when a workspace is created.
Open a complete project layout from one picker entry
Define reusable tabs with panes split right or down, custom split ratios, and a working directory, environment, and startup command for each pane. Open your editor, development server, and logs together; reconnecting keeps the running layout intact. See the pane layout walkthrough and diagram for a complete configuration.
Requirements¶
These requirements apply to the Herdr TUI plugin. For the desktop app, follow the Herdr app setup.
- Herdr 0.8.2 or newer
- Linux or macOS
- Git and Go 1.26.4 or newer for Herdr's source-based plugin installation
- Optional:
zoxidefor directory history andezafor the default preview - Optional:
fzfandbatfor the experimental fzf picker
Install¶
For Herdr TUI, install the plugin:
First use¶
From a running Herdr TUI session, open the picker through the installed plugin action:
In the Herdr app, open the sesh mod instead.
You should see your running Herdr workspaces. If zoxide has recorded directories, those appear too. Type part of a name or path, then press Enter to focus an existing workspace or create one from a directory. No config file is needed.
To add your own named project, follow Create your configuration. That walkthrough shows a complete, small config file and ends by opening the new workspace from the picker.
Everyday tasks¶
- Bind the picker and previous-workspace actions to keys.
- Switch previews or change their shortcut.
- Open a project with named tabs and split panes.
- Use direct CLI commands.
- Diagnose a missing workspace or unexpected result.
Documentation versions¶
Use the version selector in the header to choose a release's documentation.
latest follows the main branch and may describe changes not yet released.
Release snapshots are available starting with v0.10.0, when the wiki was added.
For changes in each release, see the release notes.
Reference¶
- Configuration explains config discovery, workspaces, and legacy Sesh migration. Picker covers appearance, sorting, and shortcuts. Layouts covers named tabs and split panes.
- Keybindings shows how to invoke the picker and related actions from Herdr.
- Commands covers direct CLI use and installed-binary setup.
- Contributing covers local development, tests, docs, and releases.
- GitHub releases contains versioned source and release notes.