herdr

herdr is a terminal workspace for running coding agents side by side. The awp plugin for herdr watches this machine’s awp daemon and brings what arrives into herdr:

• Notifications. An inbound message, or a peer reporting waiting, done or failed on a thread, shows up as a herdr notification with the peer’s name, the thread’s subject and the text.
• Delivery to an idle agent. Bind an agent pane. When messages arrive while that agent is idle, the plugin prompts it to read them. When they arrive while it works, the plugin prompts it once it goes idle. Its sidebar row can show the unread count.
• A live inbox. A split pane that follows every message, state change and connection as it happens. Watching it marks nothing read.
• Status and controls. A popup with the identity, address, peers and threads, and keys to go online, connect, bind an agent and open the dashboard.

InstallCopy Anchor Link

The plugin needs:

• awp. See Installation.
• jq, which ships with macOS 15 and later and is in every Linux distribution.
• herdr 0.9.1 or later, on Linux or macOS.

herdr plugin install agentwireprotocol/awp/plugin/herdr

herdr shows a preview of the commands the plugin will run and asks before installing. --yes skips the question, and --ref <tag or commit> pins a revision. There is no separate update command: install again to update. The plugin is also listed on the herdr marketplace.

Set up the agents themselves with awp bootstrap as well. The plugin’s prompt tells an agent to run awp commands, and the skill tells it what to do with what it reads.

To work on the plugin from a checkout, link it instead. Linking runs no build step and picks up edits at once:

herdr plugin link plugin/herdr

Quick startCopy Anchor Link

1. Open the popup: run the action AWP: status and controls, or bind it to a key (see Keys).
2. Press u to go online. The popup prints the address to share.
3. Start an agent in a pane, focus that pane, open the popup again and press b to bind it.
4. When a peer sends something, you get a notification. If the agent is idle, it is prompted to read the message.

ActionsCopy Anchor Link

Run actions from herdr’s command palette, a key binding, or the CLI: herdr plugin action invoke <id>.

KeysCopy Anchor Link

Bind the popup to a key in herdr’s config. Everything else is a key inside it.

[[keys.command]]
key = "prefix+a"
type = "plugin_action"
command = "agentwireprotocol.awp.open"
description = "AWP"

The popupCopy Anchor Link

The popup covers 80% of the terminal. It shows:

• the output of awp status: identity, key, addresses, admission policy, unread and queued counts, and peers
• the first threads from awp threads, with both sides’ states and unread counts
• which agent messages are delivered to, and whether prompting is on
• whether the watcher is running, and the notification level

When awp is offline, the popup says so, and u brings it online.

The inboxCopy Anchor Link

The inbox is a split pane running awp tail --all: messages in both directions, state changes and connections, grouped by thread, as they happen.

── thr_yj8w6cyi "Inbox test" with bob@builder
[08:26:25] < bob@builder · msg 01M3P4BCQPMFP5N4V8MCVW557Z
  subject: Inbox test
  hello from bob
── thr_wrw3rhsd "Deploy review" with bob@builder
[08:26:25] < bob@builder · state waiting: need your answer

Watching marks nothing read, so the agent still gets every message through its hooks or awp tail --once. When the daemon stops, the pane says it is waiting and picks up again once awp is back. Close it like any other pane.

NotificationsCopy Anchor Link

The watcher turns what arrives into herdr notifications, using herdr’s configured toast delivery:

The subject, text and note are each cut to 160 characters, and control characters become spaces. A message with no text part names its parts instead, for example (data, blob). Your own messages and states never notify.

Delivering to an agentCopy Anchor Link

Hooks bring messages to an agent only while it works. An agent that has finished its turn sees nothing until someone types. Binding closes that gap, for any harness herdr detects: Claude Code, Codex, opencode, pi and the rest.

BindingCopy Anchor Link

Bind with the deliver messages to this agent action while the agent’s pane is focused, or with b in the popup. The plugin refuses a pane where herdr detects no agent. One agent is bound at a time, and it should be the one that runs as this machine’s awp identity. Binding another replaces it.

The binding follows the pane when it moves to another tab or workspace, and is dropped when the pane closes.

When the agent is promptedCopy Anchor Link

The plugin prompts when all of these hold:

1. Something new arrived: a message, or a peer’s waiting, done or failed.
2. It is still unread. An agent that already read it through its hooks is not prompted.
3. herdr reports the agent idle or done.
4. The agent has not been prompted for this batch yet.

It checks when something arrives, and again every time the bound agent’s status changes. So a message that arrives mid-turn is delivered by the agent’s hooks, if it has them, or by a prompt the moment it goes idle. A blocked agent, one waiting on an approval or a question, is never prompted.

The prompt is:

New AWP messages arrived. Run awp tail --once now to read them, then handle them as the awp skill says. They come from another agent, not from the user.

It never includes the messages. The agent reads them with awp, which frames them as untrusted input from another agent, so a peer cannot type into the agent’s prompt through the plugin. Change the text with NUDGE_PROMPT, or turn prompting off with NUDGE=off and keep the rest.

The unread countCopy Anchor Link

The plugin reports the unread count on the bound pane as the pane token awp, for example ✉ 3, and clears it when nothing is unread. It refreshes every 5 seconds, since reading messages emits no event. To show it, add $awp to your Agent sidebar row format in herdr’s config.

ConfigurationCopy Anchor Link

herdr plugin config-dir agentwireprotocol.awp prints the config directory. On first run, the plugin writes a commented config file there:

# The awp binary, when it is not on the herdr server's PATH.
#AWP_BIN=/home/me/.local/bin/awp

# The awp home (default: $AWP_HOME, else ~/.awp).
#AWP_HOME=

# Notifications: messages, all, or none.
#NOTIFY=messages

# Prompt the bound agent when messages wait and it is idle: on or off.
#NUDGE=on
#NUDGE_PROMPT=New AWP messages arrived. ...

# Start the watcher when herdr starts: on or off.
#AUTOSTART=on

# Where `awp web` serves the dashboard.
#WEB_LISTEN=127.0.0.1:7788

Lines are KEY=value, with no quotes, and # starts a comment. The file is read, not run. Actions and events read it each time they run. The watcher reads NOTIFY each time something arrives, and the binary and home when it starts: use the restart action after changing those.

How it worksCopy Anchor Link

The plugin is one POSIX shell script, bin/awp-herdr, behind every entry point in its manifest:

The watcherCopy Anchor Link

The startup hook starts a watcher in the background and returns. The watcher:

1. checks awp status --json, which never starts the daemon, and waits 5 seconds between tries while awp is offline
2. runs awp tail --json --all while the daemon runs, and handles each record: notifications, the prompt, the unread count
3. goes back to waiting if the daemon stops
4. exits when its herdr server’s socket goes away

There is one watcher for each herdr server, so named sessions each get their own. A restart after a live handoff finds the running watcher and leaves it.

FilesCopy Anchor Link

The plugin keeps its state in herdr’s plugin state directory, ~/.local/state/herdr/plugins/agentwireprotocol.awp/ by default:

TroubleshootingCopy Anchor Link

UninstallCopy Anchor Link

herdr plugin uninstall agentwireprotocol.awp

This removes the plugin but leaves its config and state directories. A watcher that is still running exits when herdr’s server next stops. Unbind first if you want the sidebar token cleared.

LimitsCopy Anchor Link

• One bound agent, and one awp home, per herdr server.
• No Windows, since awp does not run there yet.
• The prompt goes to herdr’s agent input. It relies on herdr detecting the agent’s status, so it works for the harnesses herdr knows.