agent wire + herdr customizations: one orchestrator, many agents
Version history
- v2.1Added supervisor groups, Codex label gotchas, and corrected setup examples
- v2Added cross-runtime coordination, phone examples, and mailbox permission clarification
- v1Original Agent Wire and Herdr orchestration workflow
v2.1: added supervisor groups, codex label gotchas, and corrected setup examples. skip to getting the labels and groups right for the new notes.
i've been working with an orchestrator and several coding agents for a while now. it's how i build &.
my main conversation is with the agent keeping track of the whole thing. other sessions implement, review, investigate, and coordinate the details with each other. i give direction, discuss tradeoffs, and make the decisions that need me.
that work spans apps. my overall orchestrator runs claude code in a terminal. i also use the codex desktop app, and i can follow the codex conversation from my phone. individual sessions can bring in their own subagents or collaborate with another runtime.
two pieces of my setup make that easier to manage.
agent wire lets claude code and codex talk to each other. a shared address book, inbox, replies, and work list. local broker. sqlite underneath. the agents stay in their own sessions.
herdr-customizations is my naming setup for herdr. hooks, a skill, and a small helper that keep task names and pending questions visible in the terminal.
together, they support how i work: one main conversation, several focused teams, and less coordination passing through me. the examples below are pieces of that workflow in practice.

the vibe. gif on giphy.
the problem: i became the message bus
running several agents is easy. keeping them pointed at the same outcome takes work.
one is implementing. another is reviewing. a third found something that changes the plan. someone is waiting on a decision, but that question is buried in a tab i haven't opened.
i used to fill those gaps by copying messages between windows. asking who was still working. trying to remember whether that checkmark meant the turn ended or the change shipped.
i wrote about the broader pattern in agents guiding agents. separate the maker, the checker, and the agent keeping track of the whole thing.
agent wire gives those conversations a shared place to happen. the herdr customization keeps the state i need visible in the tab names.
the work that keeps coming up is coordination: who owns this change, whose work does it affect, what evidence is missing, and what needs my attention. those are useful jobs for agents too.
one main conversation
my main conversation is with the orchestrator. the workers have smaller jobs.
those worker sessions can be orchestrators too. a single session might coordinate dozens of its own subagents, split up investigations, and bring the results back together.
so one tab can represent a whole team. i still mainly talk to the overall orchestrator, while each session manages the work underneath it.
me
main orchestrator
implementation session
its own subagents
independent review session
its own subagents
investigation session
its own subagents
the orchestrator keeps track of what each worker owns, what is waiting, and what evidence comes next. it can ask for an update without making me switch tabs and relay it.
that doesn't make the orchestrator infallible. a worker saying "done" is still a report. the reviewer still needs to review. tests still need to run. a merge still needs to happen.
the hierarchy gives me a place to steer the work. workers also talk directly when their tasks overlap. a deployment owner can answer a runtime worker without sending every detail through the overall orchestrator.
the overall orchestrator keeps the broader picture while workers resolve those details together.
a shared view of the work
the orchestrator needs a shared view of the work before it can follow up. so do workers trying to find the owner of something they depend on.
from a plain terminal:
agent-wire sessions --table

the shared work list in my terminal, with the herdr workspace alongside it. open the full screenshot.
inside a coding agent, the MCP tool is sessions_list.
both read the same shared work list. each enrolled session publishes its own task and status through session_update, or through the CLI's report command.
the statuses are working, waiting, blocked, idle, and done. a report can also include a repository, branch, ticket, and more detail.
freshness matters. with reporting hooks installed, a new prompt marks the previous report as needing an update. five minutes without a report or hook heartbeat makes an entry stale. heartbeats track contact, not the age of the task report. stale doesn't mean the process died. idle doesn't mean the task is finished.
only enrolled sessions appear. the list covers the agents that have joined.
the list tells an agent where to start. messages let it resolve the detail with the session that owns the work.
workers coordinate the dependencies
shared environments make that especially useful. separate branches don't stop two agents from affecting the same running system.
in one runtime comparison for &, codex was preparing a candidate build for run lab, our testing environment. another claude code session owned a change to run lab itself. before changing the environment, codex asked that session whether a deployment was active or about to start.
there was one. claude had merged a chat input fix, and its run lab deployment was still running.
that changed what codex needed to do. it had already recorded an older environment state to restore after its experiment. restoring that older state could have put the environment back before the other session's fix.
here is the exchange, shortened and paraphrased from the actual agent wire messages. the numbers are the broker's message sequence numbers; unrelated messages happened between them.
32 · codex → claude, run lab owner
my candidate build is approaching. is a lab run or deployment active? i'll record the environment before changing traffic and restore it afterward.
34 · claude → codex
yes. i merged the chat box fix in PR #3999. its run lab deployment is still running. wait for it, then capture the new state. i have no lab runs active or planned.
36 · codex → claude
i'll wait, include your admin fix in my branch, and restore the successfully deployed version after my experiment. i haven't changed cloud traffic yet.

the receiving claude session in the terminal. it identifies the overlap and replies through agent wire. open the full screenshot.
then codex explained the changed plan to me:
Another Run Lab change is deploying now. I've coordinated with its owner and will include that admin fix in this branch, then capture the new deployment state before starting the experiment. That gives us the correct version to restore afterward. No candidate traffic has changed yet.
this is the kind of coordination i want happening between workers. the deployment owner had information that changed the runtime worker's plan. they exchanged it directly, and i got the explanation of what changed.
the useful outcome here was a corrected plan before a traffic change. the test results and the eventual restore still needed their own evidence.
implementation and review, across runtimes
review is another place where the conversation matters. a handoff needs room for questions and revisions.
in that runtime work, codex was also collaborating with a different claude code session on a bug: a tool call could still be running after its enclosing script finished. the run needed to wait for the result and count late usage correctly.
claude sent its diagnosis and proposed fix. codex read the inbox, explicitly acknowledged the message, and replied with a review question:
Please prove sessionManager.appendUsage adds only late classifier usage and does not double count normal successful codemode usage already appended by Pi.
claude then revised that part of the design. its reply explained that the proposed distinction between normal and late usage couldn't be observed reliably from the engine, and proposed summing each call's usage events instead.
later, claude warned codex that it was briefly putting the old bugs back to prove the new tests failed without the fixes. it sent another message when the file was restored, with the failures it had observed. codex had context for those temporary failures instead of discovering a suddenly broken suite with no explanation.
the agents were maintaining a shared understanding as the work changed: the diagnosis, the review question, the revised approach, and the testing window. each kept its own context and tools.
that includes their native subagent systems. agent wire connects enrolled sessions; each session can organize its own team underneath. i can use the strengths of different runtimes without moving all the work into one agent's subagent system.
messages need receipts
an agent can discover enrolled recipients with agents_list, send with message_send, and read its inbox with messages_read. replies link back to the original message. there is also an explicit acknowledgement.
those distinctions matter:
- queued means the broker has it
- submitted means codex accepted the delivery request, or the claude socket write completed. it is not a receipt
- acknowledged means the recipient explicitly acknowledged it
- a reply is a reply. it doesn't prove the requested work is complete
the broker stores messages in sqlite. it supports native delivery paths for codex and claude code. the codex desktop session in these examples used the CLI mailbox commands: inbox, ack, and send. you can see the acknowledgement in the phone screenshot below.
agent wire doesn't launch workers or decide what they should do. the orchestration policy lives with the orchestrator.
following the work from my phone
following the work from my phone is part of why this setup matters to me. the terminal doesn't have to be in front of me for the codex session to explain a decision or surface something it needs.
the screenshots show two levels of the same conversation: the explanation i read, and the inbox read and acknowledgement behind it.

the plan update i could read from my phone. open screenshot.

the inbox read and acknowledgement underneath that conversation. open screenshot.
the agents and local broker continue running on the computer. the phone is my view into that session. i can follow the reasoning and give direction while the workers handle their exchanges.
herdr-customizations: make the work visible
when i'm at the computer, i want to scan the whole workspace just as easily.
herdr is the terminal workspace manager. herdr-customizations is the set of hooks and naming rules i put on top of it.

my working setup. the herdr-customizations repo includes a portable version of these naming hooks.
herdr is a terminal workspace manager with tmux-style controls. it owns the terminals and lets me keep agents, tabs, and projects together. it is its own runtime, not a layer built on tmux.
my naming setup adds a small convention:
status + stage + short task name
the first symbol tells me whether the turn is working, finished, or needs me:
| Prefix | Meaning in my hooks |
|---|---|
| ⏳ | working |
| ✅ | turn finished |
| ⚪ | ready, no active task |
| ❓ | i need to answer or decide |
| ❗ | i need to do something |
then comes the stage: investigating, building, testing, reviewing, PR open, merged, blocked, failing, or parked. the main orchestrator keeps a crown in its tab label. the grouped sidebar also marks each supervisor with a crown.
so a label can move from ⏳ 🔍 login bug to ⏳ 🛠️ login bug, then ✅ 👀 login review.
the status changes through hooks. the agent keeps the short task name and stage current as the work changes. it doesn't need a new label for every tool call.
when it needs me, the question goes in the label: ❓ ship today? · login fix. an action gets a different marker. both can raise a herdr notification. pending asks stay visible until answered.
these are my personal hooks and naming rules. agent wire doesn't require them, and the tab label isn't its source of truth. herdr's own detected agent state is separate too.
a checkmark means the turn ended. it is not a green test suite.
getting the labels and groups right
i added an agents sidebar grouped by supervisor. each supervisor sits above its workers. leads can nest beneath another supervisor, or several supervisors can sit at the top. it's a visual hierarchy, with explicit ownership behind it.
getting that working exposed a few gotchas:
-
terminal codex can use a shared daemon. in codex 0.160.0, the terminal client and the process running its tools can be separate. our helper can no longer trace a hook back to its foreground herdr pane. an inherited pane ID or the focused tab isn't proof of ownership. the helper skips uncertain bindings. for this terminal setup, i use the supported
--no-daemonflag:codex --no-daemon codex resume <session-id> --no-daemonthe second command continues the saved conversation.
-
restoring a chat can lose its launch mode. herdr 0.9.1 rebuilds the codex resume command without preserving
--no-daemon. a working setup can lose automatic labels after a restore. use the explicit resume command above. this is a herdr restore limitation in that version. -
installed hooks may still need trust and activation. codex requires review of new or changed hook definitions in
/hooks. restart or resume when needed to load changed configuration. an existing command hook reads the helper script each time it runs, so changing only that script doesn't automatically require another trust review or restart./clearisn't a reliable way to activate newly installed definitions. -
a native task title and a herdr label are separate. codex's native naming tool let us set a unique temporary title and find the one terminal showing that change. that verified the pane for a manual label update. it didn't create a permanent session-to-pane binding or repair future automatic hooks.
-
a lead's name doesn't assign its workers. our manually claimed agent wire lead was named, but had no group assignment. ownership needs explicit relationships using exact herdr agent names:
herdr-groups root tooling herdr-groups assign review toolinghere,
toolingandrevieware existing named agents. the first command makes a top-level supervisor. the second assigns its worker.syncrefreshes saved assignments; it doesn't infer who supervises a newly named agent.
claude's labels were more consistent in this setup because its integration supplied the terminal ownership we needed. the codex gap was in that runtime connection. both keep the same naming and ownership rules.
peer messages and human decisions
the agents need to know who is speaking and what that speaker can authorize. a peer's message is context for the work. it doesn't become an instruction from me.
the deployment exchange also shows this boundary in the interface. this codex desktop session was registered through the CLI mailbox fallback, without its permission mode attached. claude code held its incoming message because the receiving session was bypassing permission prompts. i approved delivery before it reached claude.
that was a gap in the mailbox integration, not a manual step required for every agent exchange. native sessions with verified, matching permission modes can deliver without that hold, subject to claude's configured inbound policy. agent wire now also reads codex's own permission metadata for native sessions and mailbox enrollments linked to their actual codex thread. unknown or mismatched modes still follow claude's review policy.

the delivery prompt from that mailbox session before its permission metadata was integrated. open screenshot.
v2: this mailbox integration gap has since been fixed in agent wire 0.3.2 (commit e465f91).
the terminal's generic wrapper said "another claude session," but the agent wire envelope identified the sender as codex-codemode-jev. the envelope is what tells us who sent this message.
approving delivery let claude read the message. it didn't approve a deployment or give the peer permission to change that session's rules. the message carried an explicit reminder to treat its contents as peer data and keep the existing task and permissions.
that distinction is part of the workflow. agents can ask questions, point out dependencies, and challenge an approach. approvals remain with the person or system responsible for them.
copy either setup, or both
agent wire and herdr-customizations are separate repos. use either on its own. agent wire handles shared reports and communication; the herdr customization keeps names and questions visible in my terminal workspace.
start with the agent wire setup for the broker, session enrollment, MCP tools, and shared reports.
for the tab names, use herdr-customizations. it includes the screenshot, setup guide, codex skill and helper, and hook examples for both clients. it works without an agent wire broker.
after copying the skill into your user skills directory, a codex pane can do this:
helper="${CODEX_HOME:-$HOME/.codex}/skills/herdr/scripts/herdr-tab.py"
python3 "$helper" name "🛠️ login fix"
python3 "$helper" ask "ship today?"
the question survives the end of the turn. once answered, the agent can call status working and carry on.
the hooks handle turn state. the skill tells the agent when to rename and how to make the ask useful. notifications are optional. install it for whichever clients you use. if you use both projects, keep these hooks alongside agent wire's reporting hooks.
what this changes about the work
agent wire is still an alpha. its native adapters use codex and claude code's local interfaces on linux and macOS, and the broker is local to one host. herdr can host other runtimes, but that doesn't mean agent wire supports all of them.
what has changed for me is how much of that coordination i have to carry. a worker can find the deployment owner, ask about timing, adjust its plan, and explain the decision. a reviewer can challenge a fix and get a revised approach back. a question that needs me can stay visible until i answer it.
i still steer the work. the agents handle more of the conversation needed to carry it out.
< EOF