Omahub
← All plugins
J

Fleet Shepherd

by Joshua Warren

Read-only Herdr agent operations and OMP usage telemetry across a local and SSH connector fleet.

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
747523c
Scanned
1 month ago

No potentially dangerous behavior detected in the analyzed commit.

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
747523c
Reviewed
1 month ago

Fleet Shepherd is a read-only monitoring panel that runs fixed, bounded subprocesses (herdr/omp) locally and via SSH with strict argv validation, fail-closed host-key checking, and output caps. The code is defensive and well-tested, with no persistence, telemetry, or mutation. The only residual risk is the inherent trust placed in user-configured SSH aliases and the local commands, which is acceptable for a developer tool.

  • Executes SSH commands to user-configured remote hosts, but only fixed read-only commands with BatchMode and StrictHostKeyChecking=yes.
  • The focus helper uses hyprctl to raise windows, which is read-only and bounded.
  • No obfuscation, persistence, credential theft, or destructive operations found.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/joshuaswarren/omarchy-fleet-shepherd --enable
Developer Tools #bar #quickshell #ai

Fleet Shepherd for Omarchy

Fleet Shepherd panel walkthrough

Animated walkthrough rendered from synthetic fixture data (scripts/make_preview.py) — it never contains a live fleet screenshot.

One read-only operations panel for Herdr agents and OMP usage across a local and SSH connector fleet.

Fleet Shepherd answers three questions from the bar: are all connectors healthy, does any agent need attention, and what is the fleet’s aggregate OMP usage?

Fleet Shepherd panel

The preview uses synthetic connector, agent, project, usage and error data.

Status: v0.1.1 local beta. Read-only fleet snapshots are implemented and live-tested; remote mutation is intentionally not implemented.

Features

  • Local connector plus optional SSH connectors
  • Herdr working/blocked/done/idle agent state by connector
  • Workspace, project, cwd, and current activity
  • OMP requests, cost, tokens, cache/error summaries and top models
  • Partial-failure and stale/offline states without discarding the last valid snapshot
  • Shared locked runtime cache keeps bar and panel on the same exact snapshot
  • Live cross-fleet filter and keyboard navigation
  • Strict byte/item/string/concurrency/time bounds
  • No network listener, database, raw-session scraping, credentials, or elevated service

Architecture

The QML plugin starts one bundled Python helper. That helper invokes only fixed commands—herdr api snapshot and omp stats --json—locally or through a fixed SSH argv. See DESIGN.md and REQUIREMENTS.md.

Omarchy panel → fleet-snapshot helper → local / SSH connectors
                                   ↘ bounded normalized JSON

Requirements

  • Omarchy Quattro / Quickshell
  • Python 3.11+ (stdlib only)
  • Herdr and/or OMP on each participating connector
  • For remote connectors: noninteractive SSH aliases with verified host keys

The plugin does not install, configure, authenticate, or manage Herdr, OMP, SSH, or Tailscale.

Configuration

Copy the example and edit connector aliases:

mkdir -p ~/.config/fleet-shepherd
cp connectors.example.json ~/.config/fleet-shepherd/connectors.json
chmod 600 ~/.config/fleet-shepherd/connectors.json

{
  "schemaVersion": 1,
  "connectors": [
    { "id": "local", "label": "This machine", "mode": "local" },
    { "id": "connector-a", "label": "Connector A", "mode": "ssh", "target": "connector-a" }
  ]
}

target is an OpenSSH Host alias from ~/.ssh/config. Put username, port, identity, proxy and host-key policy in OpenSSH—not this JSON. Unknown or changed host keys fail closed.

Keyboard

  • Start typing: filter connectors, agents, projects and models
  • Up / Down: move connector selection
  • Return / Enter: raise the terminal running the selected connector's Herdr
  • 1–4: Overview / Attention / Agents / Usage
  • Ctrl+R: refresh
  • Esc: clear filter, then close

Troubleshooting

  • Panel shows "contacting fleet…" for a long time on first ever run — the cache is empty, so the helper performs one full fleet sweep (up to 60 s). Every later open paints from cache instantly.
  • A connector reports no local herdr window when raising — Return/click raises a terminal on this machine running Herdr for that connector (herdr for local, herdr --remote <target>); it never SSHes to raise a window. Open one first.
  • herdr: command failed on a remote — verify noninteractivity by hand: ssh <host> herdr api snapshot must return JSON without a password prompt.
  • OMP shows zero for a connector — check ssh <host> "omp stats --json" exits 0; usage appears only where OMP is installed and has history.
  • Panel did not appear after reinstall — restart the shell (omarchy-shell), then omarchy plugin list to confirm enabled=true.
  • Stale data after editing connectors.json — the cache is keyed to the config; changes invalidate it on the next poll.

Install

Install directly:

omarchy plugin add https://github.com/joshuaswarren/omarchy-fleet-shepherd.git --enable

Remove

omarchy plugin remove io.github.joshuaswarren.fleet-shepherd

Optional config cleanup:

rm -rf ~/.config/fleet-shepherd

Privacy and security

Fleet Shepherd renders potentially sensitive project paths and terminal titles locally. It does not persist snapshots, transmit telemetry, or read raw OMP sessions. Connector configuration is read via a bounded no-follow, nonblocking descriptor. SSH is BatchMode and StrictHostKeyChecking=yes. Every subprocess and response has a hard deadline and byte ceiling.

Development

Tests:

python3 -m unittest discover -s tests   # helper, focus, stream isolation, doc claims
node --test tests/                      # Model.js + QML contract tests

Preview assets are generated, never screenshotted:

python3 scripts/make_preview.py         # writes preview.png + preview.gif from tests/fixtures/fleet_demo.json

python3 -m unittest discover -s tests -v
node --test tests/*.test.mjs
qmllint -I /usr/share/omarchy/shell BarWidget.qml Panel.qml
omarchy plugin validate .

License

MIT — see LICENSE.