Universal task runner, command palette and build orchestrator for Herdr — one repo, two flavors.
herdr-commander gives Herdr a unified command launcher with zero runtime
dependencies. It discovers the tasks your project already defines, filters
them as you type, and runs them where you want: a new tab, a split pane, or
the terminal you are in.
TUI plugin (classic herdr) |
GUI mod (herdr-app) |
|
|---|---|---|
| Runtime | standalone Rust binary (~1.5 MB, ratatui + crossterm) | JavaScript mod (gpui-kit), no toolchain |
| Install | herdr plugin install lurepos/herdr-commander |
copy/symlink mods/commander-gui/ into the app home |
| Open with | your plugin_action key (e.g. f1) |
f1 via mod.open, or the command palette |
| Manifest | herdr-plugin.toml |
mods/commander-gui/mod.json |
This README is the project's single documentation file. It centralizes install, configuration, usage, the demo projects and the development workflow for both flavors.
Popup near the top of the window: header with workspace name and a
(filtered/total) counter, filter input with accent border, and one row per
task — colored source tag (vscode / npm / cargo / make), task label,
and the resolved command or detail. Esc closes; placement and input screens
reuse the same palette.
Transient pane popup: Herdr Commander: <workspace> (n/total) header, filter
line, boxed task list with ▶ selection pointer and [badge] origin tags,
footer key hints. Same flow, native terminal rendering.
Both flavors share one discovery spec and one interaction flow; only the renderer and runner differ.
Walks up from the focused terminal's folder looking for .vscode/tasks.json
(the TUI searches to the filesystem root; the GUI mod caps the walk at 16
levels), then reads the siblings of the workspace it finds:
| Source | What surfaces |
|---|---|
.vscode/tasks.json |
full tasks (JSONC: comments and trailing commas), options.cwd/env, dependsOn (string or array), dependsOrder (sequence/parallel), detail, VS Code inputs |
package.json |
every script, sorted, shown as npm: <name> with the script body as detail |
Cargo.toml |
five presets: cargo: check, test, build, build --release, clippy |
Makefile |
every declared target (recipe lines, assignments and duplicates are never mistaken for targets) |
Variable expansion before running: ${workspaceFolder}, ${env:NAME}
(resolved on the machine that will run the task) and ${input:ID}.
Tasks.json labels win over generated ones on collision.
-
Pick a task from the palette (type to filter — substring over label, tag and detail).
-
Pick a placement:
Placement TUI GUI mod New tab herdr tab createrun("tab.new", { argv, name })Right split herdr pane splitrun("pane.split", { direction: "right", argv })Bottom split herdr pane splitrun("pane.split", { direction: "down", argv })Current pane text injected into the focused pane hc sendto the focused terminal -
If the task (or its transitive dependencies) references inputs, the palette asks first:
pickStringas a list,promptStringas a text field pre-filled with the default. Esc on an input cancels the whole run. -
Run. Dependencies execute first — sequential chains fail fast; parallel trees run concurrently. The TUI supervises each command in its own process group (
PGID), soCtrl+Ckills the whole tree without orphans; the GUI mod composes one shell line per launch (cd '<cwd>' && …,&&chains,a & b & waitfor parallel) and hands it to herdr-core.
| TUI | GUI mod | |
|---|---|---|
| Move | ↑/↓, j/k (when the filter is empty), wheel |
↑/↓ |
| Select / run | Enter or click |
Enter or click |
| Back / cancel | Esc (placement: back), q quit |
Esc (placement: back; input: cancel) |
| Filter | just type, Backspace erases |
just type in the input |
herdr plugin install lurepos/herdr-commander
herdr plugin list # verifyLocal checkout instead of a release:
herdr plugin link .git clone https://github.com/lurepos/herdr-commander
ln -s "$PWD/herdr-commander/mods/commander-gui" ~/.config/herdr-app/mods/commander-guiWindows: the app home is %USERPROFILE%\.config\herdr-app — copy the folder
there instead of symlinking. Developing from WSL against a Windows install:
scripts/sync-mod.sh # copy the mod over (hot reload picks it up)
scripts/sync-mod.sh check # + herdr-app.exe checkThen bind a key (or open it from the command palette → Commander).
[[keys.command]]
key = "f1"
type = "plugin_action"
command = "herdr.commander.open-picker"
description = "Open Herdr Commander"Reload without restarting: herdr server reload-config.
GUI (~/.config/herdr-app/keys.json, "global" section — %USERPROFILE%\.config\herdr-app\keys.json on Windows)
Save → live reload. A second mod.open replaces the open palette; Esc
inside closes it.
- Press your key (
f1in the examples) with a terminal focused on your project — the palette reads the focused terminal's folder. - Type to filter,
↑/↓to move,Enterto choose. - Choose the placement.
- Answer any inputs.
- The task runs in the placement you chose; its terminal belongs to herdr-core and keeps running if the window closes.
No tasks found? Both flavors offer to generate a starter
.vscode/tasks.json and Exit (the GUI mod generates the template on POSIX
machines only).
| Directory | Flavor | Rows | Showcases |
|---|---|---|---|
demo/orders-api |
TUI | 5 (vscode 2, npm 1, make 2) | pickString, promptString, options.cwd + env, ${env:} |
demo/platform |
GUI | 11 (vscode 2, npm 2, cargo 5, make 2) | composite over generated tasks (cargo+npm), double-input task, cargo presets, make with variable |
Text preview without any UI:
./target/debug/herdr-commander --dump-tasks demo/orders-api
./target/debug/herdr-commander --dump-tasks demo/platformAll demo stub scripts are echo-only; running them is safe. The
cargo: presets in demo/platform really run (tiny crate).
├── herdr-plugin.toml TUI manifest (plugin manager reads this)
├── src/ TUI: config.rs, discovery.rs, runner.rs, ui.rs, main.rs
├── mods/commander-gui/ GUI mod: main.js (palette), discover.js (pure logic), mod.json
├── demo/ demo workspaces (also parity fixtures)
├── scripts/sync-mod.sh WSL → Windows mod sync
└── .github/workflows/ test.yml: cargo test + bun test; release.yml: tagged builds
cargo test # TUI unit tests (12)
bun test mods/commander-gui/ # GUI discovery tests + cross-checks (21)
cargo build --release # release binary
herdr plugin link . # live-link the TUI pluginParity is enforced by CI: the TUI binary has a hidden
--dump-tasks <dir> flag that prints its discovered task list as JSON, and
mods/commander-gui/parity.test.js diffs it against the GUI mod's
discovery pipeline on the same trees (a synthetic fixture plus both demo
projects). Known, deliberate divergences: a string args in tasks.json is
tolerated per-task by the GUI mod, while the TUI rejects the whole file; and
the GUI mod's upward search for .vscode/tasks.json stops after 16 levels,
while the TUI walks to the filesystem root. Everything else must match.
The GUI mod is checked against the installed app too:
herdr-app check mods/commander-gui
herdr-app shot out.png # capture the rendered palette
