Mods and tools for the Herdr desktop app, built on Herdr's mod API. Named after Argus, the hundred-eyed watchman of Greek myth.
Not affiliated with Herdr or Anthropic.
| Mod | What it does |
|---|---|
argus-claude-usage |
Claude plan usage for every Claude Code account on this computer: session, weekly and per-model limits with pace, usage by surface, extra usage, and a toast near a limit. |
argus-tsk |
The tsk task board: a Tasks panel with sections and a scope picker that combines a place with a thread and an assignee, quick capture, and a task pane with status, steps, block and review cards. |
argus-pull-requests |
GitHub and GitLab pull requests: a Pull requests panel with scopes, groups and a filter, and a pane with checks, reviews, merge state and conversation, where you approve, request changes, comment and merge. |
argus-stay-awake |
A coffee-cup button at the right end of the tab row that keeps the display awake. Right-click keeps it awake until no agent is working. |
argus-toolbar |
Buttons beside Herdr's tab bar that open this repo's panel mods in a panel on the right. |
- Herdr desktop app (tested on 0.1.16), macOS or Linux.
- Node.js 20 or later, for the scripts and tests.
argus-claude-usage: Claude Code (tested on 2.1.327), signed in with a Claude plan.argus-stay-awake: macOS only, because it runscaffeinate.argus-tsk: tsk 0.13.0 or later; 0.14.0 or later to show and rename project titles.argus-pull-requests:gh,glabor both, signed in (tested ongh2.104.0 andglab1.131.0).
git clone https://github.com/s3rgiosan/argus.git
cd argus
sh scripts/install.sh # copy every mod into ~/.config/herdr-app/mods
node scripts/build-layout.mjs --switch # write the Argus layout and show itinstall.sh copies each mods/<name> folder, without its editor files (gpui-kit.d.ts, jsconfig.json); Herdr 0.1.16 does not load a symlinked mod folder. It refuses to replace a folder it did not install (--force overrides). sh scripts/install.sh argus-claude-usage installs one mod.
Herdr places mods only through layouts, and it replaces its own layouts on every start. build-layout.mjs writes a personal layout, Argus, from Herdr's current main. Every Herdr block stays, and five things change:
- a coffee-cup button at the right end of the tab bar, from
argus-stay-awake, that keeps the display awake; - a toolbar beside the tab bar, with one button per installed mod that declares a panel. The buttons sort A to Z by label, or in the order set in
argus.json; - a panel column on the right, hidden until a button opens it. It takes its width and drag limits from Herdr's own
panelblock inmain.json(368 px, 280 to 900 px today); - the pane headers use
argus-pane, a copy of Herdr'spaneheader that the script writes again from Herdr's header on every run. A pull request or task pane shows the item it holds, for example "T12 · Fix the parser", in place of the mod name. Terminal panes look as before. When the copy cannot be made (Herdr's header changed, the patched copy does not parse, or its folder cannot be written), the script says so and the layout keeps Herdr's header. It never writes into anargus-panefolder that it did not create; - the sidebar uses
argus-spaces, a copy of Herdr'sspacessidebar made the same way. A space row shows no repo or branch text after its name; the ahead and behind counts stay. Space colors carry over, because Herdr keeps them in shared state.
The layout shows in Herdr's Settings under Look with a preview picture (layouts/Argus.svg). A layout written by an earlier version as argus.json is renamed to Argus.json, and the shown layout switches to it.
Theme picks are kept per layout, so pick your theme once in Argus.
Argus reads ~/.config/herdr-app/argus.json. The install script does not create it. Without it, every setting has its default: the toolbar buttons sort A to Z by label and show an icon and a label.
{ "toolbar": { "order": ["argus-tsk", "argus-claude-usage"], "display": "icons" } }toolbar.order: the panel mod names in the order their toolbar buttons show. A button not in the list follows, sorted A to Z by label. A name that matches no button is ignored. The toolbar follows the file as you save it.toolbar.display: how the toolbar buttons show."icons"shows the icon only, with the label as a tooltip."labels"shows the label only."both"shows the icon and the label. The default is"both". A button without an icon shows its label in every mode. The toolbar block resizes to fit the buttons when the value changes.
When the file is not valid JSON, a toast says so and the defaults show. A value of the wrong type or an unknown display shows the same toast and the default for that setting only; the other setting keeps its valid value.
git pull
sh scripts/install.sh
node scripts/build-layout.mjsRun build-layout.mjs again after a Herdr update too: it rebuilds from Herdr's new main, so Herdr's changes reach the layout. Do not edit Argus.json by hand; the next build replaces it. The script never overwrites a layout it did not write, and it writes nothing if Herdr's main no longer has the blocks it attaches to.
herdr-app do layout.switch '{"name":"main"}'
rm ~/.config/herdr-app/layouts/Argus.json ~/.config/herdr-app/layouts/Argus.svg
rm -r ~/.config/herdr-app/mods/argus-pane ~/.config/herdr-app/mods/argus-spaces ~/.config/herdr-app/mods/argus-stay-awake ~/.config/herdr-app/mods/argus-claude-usage ~/.config/herdr-app/mods/argus-toolbar ~/.config/herdr-app/mods/argus-tsk ~/.config/herdr-app/mods/argus-pull-requestsnpm test # pure modules and shell scripts, with node --test
herdr-app check mods/argus-tsk # load and render a mod once
node scripts/sync-lib.mjs # after editing a lib/*.js file: copy each into the mods that import it
node scripts/sync-lib.mjs --check # exit 1 when a copy differs- Each mod lives in
mods/<name>/with aREADME.mdfor people and aRECIPE.mdfor an agent rebuilding it. lib/holds code shared by mods:ui.js(frame, headers, count badge, rows, menu rows, fields, multi-line text boxes, buttons, switch, segmented control and meters in the sizes of Herdr's own panels),icons.js(load Herdr's icon files with a fallback to a mod's own copy),menu.js(Up, Down, Enter and Escape in a menu),pool.js(run async work with a cap on how many run at once),follow.js(match the focused space to a project folder, andcompareNames, a case-insensitive name order),gate.js(one run at a time, with one queued),sync.js(which open copy runs a shared read) andorder.js(sort the toolbar buttons).argus-claude-usage,argus-pull-requestsandargus-tskimportui.js,icons.js,gate.jsandsync.js;argus-pull-requestsandargus-tskalso importmenu.jsandfollow.js,argus-pull-requestsimportspool.js, andargus-claude-usageimportsfollow.jsforcompareNames;argus-toolbarimportsorder.js;argus-stay-awakeimports none. Herdr loads a mod's files from its own folder only, so each mod carries a copy of the lib files it imports; a test fails when a copy differs.- A mod gets a toolbar button by declaring
"panel": { "label": "Usage", "icon": "icons/chart-line.svg" }in itsmod.json.
- Icons: Lucide (ISC,
mods/argus-claude-usage/icons/LICENSE-Lucide.txt). - The
get_usageapproach inargus-claude-usagefollows VladTemp27/herdr-modsusage-limits, which credits jmalicki/herdr-mod-ai-usage. No code is copied.