Skip to content

Troubleshooting

The herdr plugin commands on this page apply to the Herdr TUI plugin. For Herdr app mods, check the app setup, the binary's login-shell PATH, and the backend selection.

Check installation and logs

herdr plugin action list --plugin fullerzz.sesh
herdr plugin log list --plugin fullerzz.sesh
herdr plugin config-dir fullerzz.sesh

Check that the picker action is listed and inspect recent errors before changing configuration. Use the documentation version selector for your installed release. For direct binary commands below, first follow the shell setup.

A workspace is missing

Remote spaces are available only through the Herdr app integration. If you expect a remote entry, use the app's sesh mod or run commands with HERDR_SESH_BACKEND=app, and confirm the space appears in herdr-app ls. Registering a machine alone does not create a space. See remote space selection.

  • Clear the filter with Ctrl+U. Name and path matching can place results in different groups.
  • Confirm you are targeting the intended host. In Herdr TUI, the session's socket determines which running workspaces are visible. The app backend lists the app's spaces.
  • Run "$sesh_bin" list --json and check the active config with "$sesh_bin" config path.
  • Check list.blacklist and deduplication with list --blacklisted and list --hide-duplicates=false. These options bypass the normal list cache.
  • Directory-history results require zoxide to be available and populated. Configured workspaces require a valid [[workspace]] entry.

The list cache lasts five seconds and does not cache the picker. Repeatedly clearing state files is not necessary to refresh picker results.

Configuration changes have no effect

Run "$sesh_bin" config path and "$sesh_bin" config validate in the same shell context used to invoke the plugin. An explicit HERDR_SESH_CONFIG takes precedence over the plugin config directory. See the full lookup order.

Herdr action bindings belong in Herdr's config; picker appearance and keys.cycle_preview_mode belong in the plugin config. Native plugin files need version = 1 and reject unknown keys. Reopen the picker after changing its configuration. Startup commands and tabs apply when creating a workspace, not when focusing an existing one.

Pane layout changes are not appearing

  • Confirm the workspace's tabs list references the layout's [[tab]] name; an unreferenced tab is not created.
  • Run "$sesh_bin" config validate after editing [[tab.pane]] entries. Pane layouts require the native config format (version = 1).
  • Layouts apply only when creating a workspace. Reopening the picker or reconnecting to an existing workspace does not rebuild its panes or rerun commands.
  • An extra initial tab or unexpected active tab depends on workspace startup and the first root pane's path/command. Check the initial-tab decision table.

If creation failed, correct the reported error first. To apply changes or rebuild the layout, save your work, stop processes as needed, close the workspace, and select it again. Running processes are preserved after failures; reconnecting does not retry the layout. See layout recovery.

Preview is unavailable or reports an error

Pane mode requires a running Herdr workspace. A configured session or directory without a running pane cannot provide a pane preview. Switch back to command mode with Ctrl+O or your configured shortcut.

Command previews use eza by default. If it is unavailable, install it or set workspace_defaults.preview to an available command, for example ls -la {}. Test the command with "$sesh_bin" preview TARGET. Commands time out after five seconds; superseded previews are canceled when the selection changes. The loading message appears only after a preview has been pending for 500 ms.

If no preview panel appears, check picker.show_preview. Narrow terminals put the preview below the list, and hiding paths does not force a side-by-side layout.

Icons or cursor animation look wrong

Source icons need a Nerd Font in your terminal. Set picker.show_icons = false to use source labels. The default eza preview has its own icon flag; customize the preview command separately if its glyphs are missing.

Set HERDR_SESH_REDUCE_MOTION=1 in the environment inherited by Herdr to disable the cursor trail. See cursor settings.

Previous workspace is unexpected

In the Herdr app, switches outside Sesh require a sesh-last layout block. The TUI plugin's lifecycle watcher and the server upgrade below do not apply to the app.

In Herdr TUI, history is scoped to the session and automatically removes closed workspaces. Use the installed fullerzz.sesh.last action to retain Herdr's plugin environment. Check logs if lifecycle tracking stops; a subsequent lifecycle hook can restart the watcher. Hiding the footer does not disable history. If sidebar switches are missing from history on Herdr 0.9.0, upgrade the running Herdr server to 0.9.1 or newer; that release restores the focus events the plugin needs. Rebuilding the plugin alone cannot restore those events. See history behavior and the watcher recovery limits.

Report a reproducible problem

State whether you use the Herdr TUI plugin or the Herdr app mods. Include the host and herdr-sesh versions, OS, native/fzf picker choice, the exact action or command, expected and actual behavior, and relevant log errors. Share a minimal config that reproduces the issue, removing private paths and commands as needed. A screenshot is useful for layout problems; include terminal dimensions and whether a Nerd Font is configured.