herdr-shell-progress

KO | EN

gitlite — search

#editor #markdown #ai-agent #monitoring #chatbot #open-source #gemini #bash #rust #react

herdr-shell-progress

(★ 9)

Herdr plugin: live sidebar progress for slow shell commands, not just coding agents

File Explorer

ZIP Download

- demo.gif
- demo.tape
- print-snippet.sh
- init.bash
- init.fish
- init.zsh
- args.rs
- command.rs
- config.rs
- label.rs
- main.rs
- proto.rs
- socket.rs
- state.rs
- watch.rs
- hooks.rs
.gitignore
Cargo.lock
Cargo.toml
config.example.toml
herdr-plugin.toml
LICENSE
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Herdr shows live progress for recognized coding agents. A pane running
`cargo build --release` for four minutes shows nothing at all.

This plugin fixes that: slow shell commands report `working` with a ticking
elapsed label, and leave a result behind when they finish.

![demo](https://raw.githubusercontent.com/bayoudhi/herdr-shell-progress/main/demo/demo.gif)

*`ls` leaves no trace; `sleep 6` crosses the threshold and appears in the
sidebar as `sleep 6 · running 4s`, then settles into `sleep 6 · ok · 6s`.*

- Fast commands are invisible — nothing flickers when you run `ls`.
- Failures stick until your next command, so you see what broke while away.
- Successes clear themselves after 20 seconds by default.
- Zero socket traffic and zero output for commands under the threshold — with
  one exception: the first command after a sticky failure label spends two
  requests wiping it, however fast that command is.

## Requirements

- Herdr >= 0.7.0
- **zsh, bash >= 3.2, or fish >= 3.1** — each has its own hook file under
  `shell/`. Any other shell needs a port; see
  [Porting to another shell](#porting-to-another-shell).
- **A Rust toolchain** — installation compiles the watcher from source. There
  are no prebuilt binaries.
- macOS or Linux. Developed and tested on macOS; the Rust and shell sides are
  all portable and Linux should work, but it has not been run there. Reports
  welcome.

## Install

```bash
herdr plugin install bayoudhi/herdr-shell-progress
```

That runs `cargo build --release` for you.

Now add the hook to your shell's rc file. Installed plugins live under a
content-hashed directory, so each snippet matches it with a glob and takes the
newest, rather than hardcoding a path that changes on every update. If the
plugin isn't installed, they do nothing.

**zsh** — append to `~/.zshrc`:

```zsh
# herdr-shell-progress
() {
  local f=(~/.config/herdr/plugins/github/bayoudhi.shell-progress-*/shell/init.zsh(Nom))
  (( $#f )) && source $f[1]
}
```

This uses zsh glob qualifiers rather than a subshell, so it costs no fork: `N`
makes a missing match empty instead of an error, and `om` orders newest-first.

**bash** — append to `~/.bashrc`:

```bash
# herdr-shell-progress
_hsp_dir=$(ls -td ~/.config/herdr/plugins/github/bayoudhi.shell-progress-*/ 2>/dev/null | head -1)
[ -r "$_hsp_dir/shell/init.bash" ] && . "$_hsp_dir/shell/init.bash"
unset _hsp_dir
```

**fish** — append to `~/.config/fish/config.fish`:

```fish
# herdr-shell-progress
for d in (ls -td ~/.config/herdr/plugins/github/bayoudhi.shell-progress-*/ 2>/dev/null)
    if test -r $d/shell/init.fish
        source $d/shell/init.fish
        break
    end
end
```

Then open a **new** pane — an rc file only runs for new shells — and run
`sleep 5`.

**That block is required.** Installing the plugin alone does nothing: Herdr can
run a plugin's own processes, but only your shell knows when a command starts
and stops, so the hooks have to live in your shell.

### bash and bash-preexec

If something already loaded [bash-preexec] — Atuin and iTerm2's shell
integration both do — the hook registers with it rather than installing a
second `DEBUG` trap, which would start two watchers per command. Nothing is
needed from you beyond loading bash-preexec before this snippet.

If some *other* `DEBUG` trap is installed and bash-preexec is not there to
share it, the hook stays inert rather than breaking whatever owns the trap.
Loading bash-preexec first makes both work.

One consequence of going through bash-preexec: it hands over the command line
but not its alias-expanded form, so an aliased command reaches the ignore list
under the alias rather than the program behind it. See
[Ignoring commands](#ignoring-commands).

[bash-preexec]: https://github.com/rcaloras/bash-preexec

<details>
<summary>Installed from a clone, or want to check the path by hand?</summary>

For a `plugin link` install, source your clone directly:

```zsh
source ~/herdr-shell-progress/shell/init.zsh   # or init.bash, or init.fish
```

To see the resolved path for an installed copy:

```bash
herdr plugin list --json \
  | python3 -c 'import json,sys;print(next(p["plugin_root"] for p in json.load(sys.stdin)["result"]["plugins"] if p["plugin_id"]=="bayoudhi.shell-progress"))'
```

There is also a `print-snippet` action, but note that
`herdr plugin action invoke` returns an invocation record on stdout and sends
the action's own output to the plugin log — so you would need
`herdr plugin log list --plugin bayoudhi.shell-progress` to read it. The glob
above avoids that entirely.

</details>

### From a clone instead

```bash
git clone https://github.com/bayoudhi/herdr-shell-progress ~/herdr-shell-progress
cd ~/herdr-shell-progress
cargo build --release
herdr plugin link ~/herdr-shell-progress
echo 'source ~/herdr-shell-progress/shell/init.zsh' >> ~/.zshrc  # init.bash / init.fish
```

`herdr plugin link` deliberately does *not* run build commands, so the
`cargo build` is required here.

## Configure

```bash
herdr plugin config-dir bayoudhi.shell-progress
```

Copy `config.example.toml` into that directory as `config.toml`. Every key is
optional. Changes take effect on your next command — no reload, no restart.

### Ignoring commands

Some commands should never be reported: interactive programs that legitimately
run for hours, and above all coding-agent CLIs. If this plugin reports on a pane
running an agent, it and Herdr's own integration both try to own that pane's
state, and yours wins — hiding what the pane actually is.

Two keys control this, and the difference matters:

```toml
# ADDS to the defaults. This is almost certainly the one you want.
ignore_extra = ["claude-personal", "terraform", "docker"]

# REPLACES the defaults entirely. Setting this drops every built-in entry,
# including the agent CLIs, unless you list them again yourself.
# ignore = ["vim", "less"]
```

Matching is on the **basename of the program name**, exactly. The command is
read after alias expansion, and leading `VAR=value` assignments plus the
transparent wrappers `command`, `builtin`, `exec`, `env` and `nohup` are looked
through. So an alias like

```zsh
alias claude-personal='CLAUDE_CONFIG_DIR=~/.claude-personal command claude'
```

matches the built-in `claude` entry without any configuration.

zsh gets the expanded form from `preexec` and bash from `$BASH_COMMAND`. fish
needs no expansion — its abbreviations are already expanded in the submitted
line, and its functions carry the name you would think to ignore.

The exception is bash going through [bash-preexec], which hands over the command
line but not its expanded form. There, an alias reaches the ignore list under
its own name, so list the alias as well:

```toml
ignore_extra = ["claude-personal"]
```

A **wrapper script** is different: it is a real program, and the agent it runs
is invisible from the outside, so it needs its own entry. Same for a renamed
build. If a pane shows a long "running" label for something that isn't really a
shell command — or the pane's own agent looks like it has been taken over —
this is why:

```bash
printf 'ignore_extra = ["my-wrapper"]\n' \
  >> "$(herdr plugin config-dir bayoudhi.shell-progress)/config.toml"
```

It applies on your next command — no reload, no restart.

Defaults: `vim`, `nvim`, `less`, `man`, `ssh`, `top`, `htop`, `zsh`, `bash`,
`sh`, `fish`, `claude`, `codex`, `opencode`, `droid`.

## Where shell commands show up

They appear in the sidebar's **agents** list, alongside your coding agents.
That is simply where Herdr shows pane status; a plugin cannot add a section of
its own, and there is no setting to filter or separate them.

What the plugin does do is report a **constant agent id**, `shell`, for every
command. Without that, each distinct command would mint its own agent identity
and your list would fill up with `cargo`, `sleep`, `make`, and every other
binary you ever ran. One id keeps it to a single kind of entry. The row still
shows the actual command — the line as you typed it, so `npm run start` rather
than a bare `npm` — sent as `display_agent`, which Herdr renders in preference
to the id.

Row names are cut at `max_display_len` (24 characters by default) with an `…`
marking the cut, and runs of whitespace are collapsed so the row stays tight.
Raise or lower it in `config.toml`:

```toml
max_display_len = 32
```

Keep it under Herdr's own `ui.sidebar_max_width`, which defaults to 36 columns.
The row spends columns on the state icon and the elapsed label too, so a wider
cap does not widen the name — Herdr truncates it again, and the elapsed label is
what gets squeezed out.

The ignore list is unaffected by any of this: it still matches on the program
name alone, as does the `{agent}` label variable.

**These entries cannot be restyled.** Herdr's `rows_by_agent` table is validated
against its own canonical agent ids (`claude`, `codex`, `gemini`, and so on) and
rejects anything else. It rejects it by refusing to parse the entire config
file, so adding a rule for this plugin does not merely fail to apply — Herdr
silently falls back to default settings and you lose your keybindings and theme
until you remove it. An earlier version of this README recommended exactly that;
if you followed it, delete the rule and run `herdr config check`.

If you would rather a command never appear at all, that is what
[`ignore_extra`](#ignoring-commands) is for.

### Showing the elapsed label

Herdr's default sidebar rows are:

```toml
rows = [["state_icon", "workspace", "tab"], ["agent"]]
```

There is no `state_text` in there, so out of the box you get the spinner and the
command line but **not** the `running 4s` label — the plugin reports it, and
nothing displays it. To see what the demo above shows, add `state_text` to the
second row in your Herdr `config.toml`:

```toml
[ui.sidebar.agents]
rows = [["state_icon", "workspace", "tab"], ["agent", "state_text"]]
```

Then `herdr config check` and `herdr server reload-config`. This is the plain
`rows` key, which accepts any of Herdr's built-in row fields — unlike
`rows_by_agent` above, it is not restricted to canonical agent ids.

This also affects the finish labels: `ok · 4s`, `exit 1 · 12s`, and `SIGINT · 3s`
all live in `state_text`.

## How it works

The pre-command hook spawns a detached watcher. The watcher sleeps until the
threshold; if the command finishes first it exits having never touched the
socket. Otherwise it reports via `pane.report_agent` and ticks
`pane.report_metadata`. The pre-prompt hook writes the exit code and signals the
watcher, which posts the final label and exits.

Under zsh that costs one fork per prompt — the watcher itself — because
everything else is a builtin. bash pays a second fork to read `history 1`, and
fish a second fork for `kill`, which it has no builtin for.

The watcher writes nothing to stdout or stderr — it inherits the pane's tty, so
any output would corrupt your shell session.

## Porting to another shell

The Rust watcher is shell-agnostic. Everything shell-specific lives in
`shell/init.zsh`, `shell/init.bash` and `shell/init.fish`, each about 50 to 100
lines, and a port needs to do three things:

1. On command start: write the command line to `<state-dir>/cmd`, then spawn
   `herdr-shell-progress watch --pane "$HERDR_PANE_ID" --shell-pid <shell pid>
   --start-ms <epoch ms> --state-dir <state-dir>`, detached, with both streams
   redirected to `/dev/null`. Pass `--clear-first` if `<state-dir>/marker`
   exists. A shell with no cheap millisecond clock can pass `--start-now`
   instead of `--start-ms` and let the watcher read its own.
2. On command end: write `$?` to `<state-dir>/exit`, then send `SIGUSR1` to the
   watcher.
3. On shell exit: send `SIGTERM` to the watcher.

There is one optional fourth: a shell whose pre-command hook cannot see both the
whole command line and its alias-expanded form — bash is the only one so far —
can write the expanded leading command to `<state-dir>/name`, and the watcher
will match the ignore list against that instead of against `cmd`. The file is
consumed on read.

New hooks belong in `tests/hooks.rs`, which drives each one through a real
interactive shell on a pty and checks what it spawned. PRs welcome.

## Uninstall

```bash
herdr plugin uninstall bayoudhi.shell-progress
```

Use `herdr plugin unlink bayoudhi.shell-progress` instead if you installed from
a clone with `plugin link`.

Then remove the block from your shell's rc file. It is what actually runs the
plugin, so leaving it behind after uninstalling leaves a dangling `source` that
your shell will complain about on every new pane.

herdr-shell-progress

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README