pj-herdr

A herdr plugin that brings pj project jumping to herdr workspaces.

Press Ctrl-s O → fuzzy-search your projects → hit Enter → herdr creates or switches to that project's workspace.

How it works

• Opens a popup pane (floating, ~80×80% of the screen) with a fuzzy project picker (Television or fzf, your choice)
• Enter switches to an existing workspace for that project, or creates one if none exists
• Extra keybindings for power users: new workspace, open in editor, new tab, clear cache
• Prefer the old overlay style instead? Override --placement popup with --placement overlay in your own pj.open-picker keybinding (see Installation below)

Prerequisites

• herdr ≥ 0.7.4
• pj — project directory manager
• jq — JSON processor (used for workspace lookup)
• One of:
  • Television (tv) — rich picker with preview pane (recommended)
  • fzf — widely-available fallback
• eza (optional) — prettier tree preview; falls back to tree or ls

Installation

herdr plugin install josephschmitt/pj-herdr

Then add a keybinding of your choice to ~/.config/herdr/config.toml:

# pj project picker
[[keys.command]]
key = "prefix+o"
type = "plugin_action"
command = "pj.open-picker"

Then reload:

herdr server reload-config

Configuration

Create a config file at $(herdr plugin config-dir pj)/config:

mkdir -p "$(herdr plugin config-dir pj)"
echo "picker=tv" > "$(herdr plugin config-dir pj)/config"

All options are set in the config file as plain key=value pairs.

Option	Default	Description
picker	auto	Picker backend: tv, fzf, or auto (prefers tv)
sort	alpha	Sort order: alpha, priority, or label
sort_direction	(pj default)	Sort direction: asc or desc
icons	true	Show marker-based icons (requires a Nerd Font)
ansi	true	Colorize icons with ANSI codes
worktrees	auto	Include git worktrees: auto (pj default), yes, or no
max_depth	(pj default)	Maximum directory search depth
no_nested	false	Skip projects nested inside other projects

Commands

Command	Description
pj.open-picker	Open the project picker popup

Once inside the picker:

Key	Description
Enter	Switch to workspace (create if none exists)
Ctrl-n	Always create a new workspace
Ctrl-w	Open as a new herdr worktree
Ctrl-e	Open project in $EDITOR
Ctrl-t	Open new herdr tab with project as CWD
Ctrl-r	Clear pj cache and reload project list

Development

cd ~/development/pj-herdr

# Link for local development
herdr plugin link .

# Make scripts executable
chmod +x scripts/*.sh

# Reload herdr config
herdr server reload-config

Links

• herdr — terminal workspace manager
• pj — project directory manager
• Television — fuzzy finder with preview
• herdr plugin docs