跳到正文
DEV Community· Evan Lin·· 7 小時前AI 評分47

Herdr 實戰:自行建立 Herdr mod,以標籤建立「待審核」佇列追蹤尚未查看的報告

[Herdr in Practice] Build Your Own Herdr Mod: Create a "Pending Review" Queue with Labels to Instantly Track Unread Reports

AI 導讀

作者為 Herdr 編寫 review-queue mod,以終端標籤建立「待審核」佇列,追蹤哪些 coder 已回報但尚未查看。配套的 hc-review CLI 讓 coder 設定 review=ready 並傳送報告,審閲者標記 review=seen 後,項目便會移至已查看區域。mod 透過 terminals() 即時讀取標籤變化,並可彈出通知及跳轉至對應 Pane。

正文

review-queue panel: In the middle is the pending review queue, two agy coders just reported using hc-review ready

Recap

The previous two posts (First time using Herdr, Using two agy Panes for record2gif) followed the same pattern:

  • Left side: Claude Code as PM / Reviewer, opening issues, reviewing, and committing.
  • Right side: agy as coder, reporting via hc send when finished.

After using it for a while, there's a practical issue: coder reports are typed directly into the PM's input box. After opening two or three coders and going through several rounds, it's hard for me (the human) to answer:

Which coders have reported now? Which ones have I seen, and which ones haven't I?

The done status in the Herdr sidebar doesn't help because as soon as you glance at that Pane, it reverts to idle. "Seeing" is not the same as "reviewed."

While searching online for the previous post, I also found that writing your own Herdr mod is a topic almost no one in the Chinese-speaking community has written about. So this time, I'll make one myself:

A "Pending Review" queue panel: listing which coders have reported and haven't been seen yet.

Result: kkdai/herdr-review-queue


1. Discovery before starting: hc send is invisible

My original idea was intuitive: have the mod listen for hc send messages. If someone sends a message to the reviewer, add it to the queue.

But I actually tested hc events (the real-time event stream of herdr-core):

hc run --bg --name probe-target cat
hc run --bg --name probe -- sh -c 'hc events --json'
hc send probe-target "probe message"
hc label probe-target review=ready

It turns out the events contain foreground, title, labels... but no send. Messages only appear in the recipient's input box and cannot be observed by outsiders.

However, this experiment also found a way out: label changes appear in events in real-time, and the mod API's terminals() also brings up the labels for each terminal in real-time.

So the design shifted to:

Instead of peeking at messages, let the coder "incidentally" stick a label on their own terminal when reporting.


2. Label contract: The agreement between coder and reviewer

Labels are placed on the coder's own terminal (hc label <t> k=v, where k= means removal):

Label Value Set by
review ready or seen (none = not in queue) ready: coder; seen: reviewer
review.summary One-line summary, max 200 chars coder
review.at Time when it became ready (ms) coder
review.to Reviewer's address (e.g., t15) coder
review.seen_at Time when marked as seen reviewer

By the way, I confirmed two things: label keys can contain ., and values can handle Chinese and full-width punctuation without issues.

sequenceDiagram
    participant C as agy coder (t1k)
    participant H as herdr-core
    participant M as review-queue mod
    participant R as Claude Code (t15)

    C->>H: hc-review ready "Summary"<br/>→ hc label t1k review=ready ...
    C->>R: hc send t15 "[review-ready] Summary"
    H-->>M: terminals() Real-time update
    M->>M: Queue +1, pop-up notification
    R->>H: Click Seen → hc label t1k review=seen
    H-->>M: Queue -1, move to Seen area

This table was written directly into the SPEC, becoming the sole interface between the two issues.


3. PM Workflow: One SPEC, 3 Issues, two Panes

The workflow is the same as in the record2gif post:

# Issue Who Round
1 hc-review CLI + Tests agy Pane A Round 1
2 review-queue Herdr mod agy Pane B Round 1 (Simultaneous with #1)
3 install.sh, README, Screenshots agy Pane A Round 2

Since the label contract was hardcoded in the SPEC, #1 and #2 didn't have to wait for each other at all and could start simultaneously. Each issue had its own git worktree; coders didn't commit or push, as everything was handled by Claude Code after review.

Both coders were agy (Antigravity CLI) running Gemini 4 Argon.


4. hc-review: A small CLI for coders

The command for coders is simple, written in POSIX sh, and only depends on hc and jq:

hc-review ready "<summary>" [--to <t>] [--no-send] # coder reports
hc-review seen <t> # reviewer marks as seen
hc-review clear <t> # clears all review labels
hc-review ls [--all] [--json] # terminal version of the queue

ready will:

  1. Find its own parent from hc get $HC_TERMINAL_ID --json to use as the default reviewer.
  2. Attach review=ready, summary, time, and reviewer to itself.
  3. hc send a [review-ready] <summary> message to the reviewer.

So the prompt for the coder just needs one more sentence:

When finished, run hc-review ready "<one-sentence summary: what changed, test results>" to report.


5. How to write a Herdr mod

This is the part I want to share the most. Herdr mods are located in ~/.config/herdr-app/mods/<name>/, consisting of a main.js and a mod.json:

{ "place": "right", "size": 340, "title": "Review queue" }

main.js is JavaScript, which default exports a class inheriting from View. The UI is built using a GPUI-style chained builder (no HTML/CSS). Key concepts:

Concept Description
terminals() All terminals (including labels), real-time: when data changes, render() reruns automatically; no need to poll manually.
hc([...]) Run hc commands directly within the mod, e.g., calling hc label when clicking Seen.
run("agent.focus", …) Execute Herdr commands, e.g., jumping to that coder's Pane.
notify({...}) Pop up a notification; clicking it can execute a command.
theme() Use theme colors; both dark and light themes will adapt.
nextCommand() Receive shortcut commands, e.g., review-queue:next.

The simplified skeleton looks something like this:

import { View, div } from "gpui-kit";
import { v_flex, h_flex } from "gpui-base";
import { terminals, hc, run, notify, theme } from "herdr";

export default class ReviewQueue extends View {
  render() {
    const t = theme();
    const pending = terminals()
      .filter((x) => x.labels?.review === "ready")
      .sort((a, b) => Number(a.labels["review.at"]) - Number(b.labels["review.at"]));

    return v_flex().size_full().bg(t.chrome).children(
      pending.map((x) =>
        h_flex().id(`rq-${x.address}`).gap(8)
          .on_click(() => run("agent.focus", { terminal: x.address }))
          .child(div().child(x.name ?? x.address))
          .child(div().text_color(t.muted).child(x.labels["review.summary"] ?? ""))
          .child(div().id(`seen-${x.address}`).child("Seen")
            .on_click((_e, cx) => {
              cx.stop_propagation();
              cx.spawn(async () => {
                await hc(["label", x.address, "review=seen", `review.seen_at=${Date.now()}`]);
              });
            }))));
  }
}

The actual version includes: a Seen area (collapsible, up to 10 entries), Reopen / Clear, relative time, status dots, error messages displayed on the row for 5 seconds, and notifications only for new reports (no notifications for items already in the queue when the mod starts).

A few rules for writing mods (all documented in Herdr's AGENTS.md, and the coder followed them):

  • Don't poll terminals(): it is inherently real-time. The only timer is for updating relative times like "3m, 2h" every 30 seconds.
  • Don't retain cx: each callback receives its own cx.
  • Use theme colors only; don't hardcode colors.
  • Run herdr-app check mods/review-queue after every change.

6. Issues caught during Review

#1: 13 tests passed, but running with real hc resulted in an empty table

The CLI delivered by coder A was beautiful, passing all 13 tests. But when I tested it with real hc in a temporary terminal:

$ hc-review ready "e2e test" --no-send
{"address":"t1n","argv":[...huge blob of JSON...]}
$ hc-review ls
ADDRESS NAME AGE SUMMARY

Two issues:

  1. ls was always empty. The reason is that the real hc ls --json only returns a summary (address, agent, status...), and doesn't include labels or name at all.
  2. hc label prints the entire terminal JSON to stdout, so the user sees a huge blob.

So why did the tests pass? Because the fake hc used for testing was written by the coder, and it made ls --json return data containing labels. The fake was different from the real thing; the tests were just validating their own assumptions.

The fix: ls now fetches the address list first, then runs hc get --json for each address to get full data; hc label's stdout is redirected to /dev/null, printing a single line ready: t1k → t15 instead; the fake hc for testing was updated to simulate real output formats.

This is the same takeaway as the record2gif post: passing all tests is not the same as being actually usable. This time, "fake dependencies" fooled the tests.

#2: Passed on the first try, but check only verified half

The mod passed herdr-app check on the first try. However, check only renders once with empty data, so the rows that only appear when there is data were never executed. Therefore, I manually verified that every builder method used in the rows (text_ellipsis, line_height, border_l...) existed in gpui-kit.d.ts before approving. The actual UI was left for real-world testing after installation.

#3: Installed, but not visible on screen

install.sh used a symlink to install the mod into ~/.config/herdr-app/mods/review-queue. check passed, but the panel didn't appear. mod.json specified "place": "right", but Herdr didn't automatically add it to the layout. I suspect the symlinked folder wasn't detected as a new mod.

The solution was to manually open a Pane:

herdr-app do pane.split --direction right --mod review-queue

I also asked the coder to add this step to the README.


7. A real run-through

After installation, I asked two coders to each run hc-review ready:

  1. The PM's input box received two <hc from="t1k rq-coder-a">[review-ready] ...</hc> messages.
  2. The panel immediately showed Review queue 2, with two cards containing names, summaries, times, and Open / Seen buttons (as seen in the top image).
  3. After executing hc-review seen, the panel updated to 0 without a refresh, and the two entries moved to Seen 2:

After clicking Seen: Queue returns to zero, two entries moved to the Seen area

A small tip: herdr-app shot saves the "last frame drawn" of the window. If Herdr isn't in the foreground, it might be an old frame. I encountered old screenshots twice; calling the window to the front with open -a Herdr before capturing fixed it.

Not yet verified: I haven't actually clicked the buttons on the panel with a mouse (Herdr's guideline is to avoid pointer automation on real screens, so Seen was tested via CLI; both send the same hc label); notifications for new reports and the review-queue:next shortcut haven't been tested yet either.


8. Checklist for writing Herdr mods

  • 1. Read ~/.config/herdr-app/AGENTS.md and herdr.d.ts first: The APIs are all there. Built-in mods (agents, toast, terminals-pane) are the best examples.
  • 2. Confirm data availability first: If I had started by listening for send, the whole round would have been wasted. A few minutes of testing with hc events revealed this.
  • 3. Use labels for state between agents: hc label is real-time, visible to mods, and queryable via CLI.
  • 4. Don't poll real-time data: terminals(), agents(), and spaces() trigger a re-render when they change.
  • 5. herdr-app check only verifies empty states: Code that only runs when data is present must be verified separately.
  • 6. Fake dependencies must simulate real output: Run the real hc once and copy the actual JSON format into the fake.
  • 7. Symlink installation won't auto-dock: Open it using pane.split --mod <name>.
  • 8. Bring Herdr to the foreground before taking screenshots, otherwise herdr-app shot might capture an old frame.

Summary

  1. Herdr mods are easier to write than expected: Just one main.js, data is real-time, and it reloads on save. This time, a complete panel was built in 451 lines.
  2. Verify data sources before designing: hc events lacks send events. This discovery shifted the design from "listening to messages" to a "label contract," allowing the CLI and mod to be developed in parallel.
  3. The most valuable part of a review is "running it for real": A CLI that passed 13 tests resulted in an empty table when run with real hc.
  4. Tools are starting to help my own workflow: Now, when a coder reports by running hc-review ready, I can see at a glance on the panel who is waiting for me.

The repo is at kkdai/herdr-review-queue. You can install it with ./install.sh. Feel free to use it.

來源:DEV Community · dev.to