Agent Tooling Guide
Hermes Agent + herdr: Supervising Hermes in an Agent Multiplexer
herdr is a terminal multiplexer built for AI coding agents, and Hermes Agent is one of the agents it knows how to read. If you have seen the two names together, this guide explains what herdr actually does with Hermes, how to set up the official integration, and where herdr stops being the right tool. Details come from the current herdr docs and source.
What herdr is
herdr describes itself as “the runtime your coding agents live on”. In practice it is a tmux-style workspace for people who run several AI agents at once. It splits your terminal into panes, keeps them running in a background server when you detach or lose SSH, and, unlike tmux, knows which panes hold an agent and what that agent is doing.
Each agent pane is marked working, blocked or idle, and those states roll up to tabs and workspaces. A blocked agent makes its whole workspace look blocked, so you jump straight to the one waiting on an answer instead of cycling through terminals. herdr runs Claude Code, Codex, Cursor, OpenCode, Grok and others as they are; it owns their terminals rather than wrapping them.
It is a single Rust binary, free and open source under Apache 2.0 (relicensed in July 2026), and installs with brew install herdr, mise use -g herdr or the upstream install script. For a side-by-side of herdr and a hosted agent, see OpenClaw Launch vs herdr.
Where Hermes fits
Hermes Agent runs in two ways. As a gateway it sits on Telegram, Discord, Slack and other platforms with memory, skills and scheduled jobs. As a local program it has an interactive CLI and TUI you drive from a terminal, often for coding or research work. herdr only concerns the second mode: a Hermes session running in a terminal pane.
Hermes Agent is on herdr’s official supported-agents list, with this setup:
| Aspect | How herdr handles Hermes |
|---|---|
| Detection | Recognises the hermes foreground process (alias hermes-agent) |
| State source | Screen manifest: rules matched against the bottom of the live pane and the terminal title |
| Integration role | Session identity only, used to resume the pane after a herdr restart |
| Resume command | hermes --resume <id> |
What herdr reads as “blocked” in Hermes
This is the useful part if you let Hermes work unattended in a pane. herdr’s Hermes manifest marks the pane blocked when the screen shows prompts that need you, including:
- a dangerous-command approval (allow once / deny)
- a clarification question where Hermes asks you to type an answer
- a sudo password or skill-setup credential prompt
- a confirmation such as approve once / cancel, or start a new session / keep going
It reads working from Hermes’s interrupt hint and the progress glyph in the terminal title, and idle from the finished-turn title. herdr is deliberately strict here: if Hermes shows a prompt shape the manifest does not know yet, the pane may read idle rather than blocked. herdr updates manifests from herdr.dev in the background, and herdr agent explain <pane> shows which rule matched when a state looks wrong.
Set up Hermes in herdr
Install Hermes first (see Install Hermes Agent) so its config directory exists, then install herdr and its Hermes integration:
brew install herdr # or: mise use -g herdr
herdr integration install hermes # adds the herdr-agent-state plugin
herdr integration status # confirm it is installed and current
herdr # start herdr where the work livesThen start hermes in a pane. What the integration does, per the herdr docs:
- Writes
plugins/herdr-agent-state/under the Hermes home (~/.hermes, orHERMES_HOMEif set;%LOCALAPPDATA%\hermeson Windows). - Adds
herdr-agent-statetoplugins.enabledinconfig.yaml, preserving the rest of the file. - Reports the Hermes session id only while Hermes runs inside a herdr pane, and only from interactive surfaces such as the CLI and TUI. Gateway conversations are ignored.
Restart Hermes after installing so the plugin loads. Without the integration, herdr still detects Hermes and shows its state; you only lose session restore. herdr integration uninstall hermes removes the plugin and the config entry. More on how Hermes loads plugins in Hermes Agent plugins.
Session restore after a restart
Detaching (ctrl+b q) leaves panes running in herdr’s background server. A full server or machine restart is different: the original processes do not survive. With a current Hermes integration (version 5 or later), herdr restores the saved layout and restarts the pane with hermes --resume <id>, putting you back in the same Hermes conversation. You can turn this off with [session] resume_agents_on_restore = false in herdr’s config.
A typical Hermes + herdr layout
herdr earns its place once there is more than one agent to watch. A common shape:
- One pane with Hermes doing research, drafting or running a long task with its tools.
- One or two panes with coding agents such as Claude Code or Codex working in separate checkouts.
- A shell pane for tests and git.
You glance at the sidebar, answer whichever agent is blocked, and leave the rest alone. herdr also has a CLI and socket API that let agents spawn panes, prompt each other and wait until another agent is genuinely blocked, but that is optional; the core value is the state view. If you would rather have Hermes itself hand coding work to another agent, see Hermes Agent + Codex and Hermes Agent + Claude Code.
herdr, tmux or a hosted Hermes bot?
| You want | Use |
|---|---|
| Several agents in one terminal, with a view of which one needs you | herdr |
| Plain panes and persistence, no agent awareness | tmux is enough |
| Your Hermes session back after herdr or the machine restarts | herdr + herdr integration install hermes |
| Hermes answering on Telegram or Discord while your computer is off | A hosted Hermes gateway, not a terminal tool |
| Memory, cron jobs and skills that keep running unattended for weeks | A hosted Hermes gateway |
The line from the herdr comparison holds for Hermes too: if your problem disappears when you close the laptop, it is a herdr problem; if it starts when you close the laptop, it is a hosting problem. herdr keeps sessions alive across a closed client or a dropped SSH link, but the machine running the herdr server still has to be on.
On OpenClaw Launch
A managed Hermes bot on OpenClaw Launch runs as a gateway in our cloud and talks to you through chat platforms and the web dashboard, not a local terminal pane, so herdr has nothing to attach to there and you do not need it for that bot. The two coexist without any shared state: herdr on your machine for the agents you actively drive, and the hosted bot for the assistant that keeps answering, remembering and running schedules when you step away. To weigh self-hosting against a managed bot first, Best Hermes Hosting compares the options.
Hermes + herdr FAQ
Does herdr support Hermes Agent?
Yes. Hermes Agent is on herdr’s supported-agents list. herdr recognises the hermes process and uses a screen manifest to mark the pane working, blocked or idle. An optional integration, installed with herdr integration install hermes, adds session identity so herdr can resume the pane later.
What does herdr integration install hermes change?
It writes a small plugin to plugins/herdr-agent-state/ under your Hermes home (~/.hermes by default, or HERMES_HOME) and adds herdr-agent-state to plugins.enabled in config.yaml. Restart Hermes afterwards. herdr integration uninstall hermes removes both.
Can herdr watch my Hermes bot on Telegram or Discord?
No. herdr watches terminal panes. It sees Hermes when you run the interactive CLI or TUI inside a herdr pane, and the plugin only reports sessions from interactive surfaces such as the CLI and TUI. Conversations handled by the Hermes gateway on Telegram, Discord or Slack happen outside any pane, so herdr has nothing to observe there.
Is herdr free, and what licence is it under?
herdr is free and open source. It was relicensed to Apache 2.0 in July 2026, and ships as a single Rust binary for macOS, Linux and Windows. You still pay for whatever models Hermes and your other agents call.
Should I use herdr or a hosted Hermes bot?
They answer different questions. herdr helps when you run several agents at your desk and need to see which one is waiting on you. A hosted Hermes bot helps when you want an agent that keeps answering in your chat apps while your computer is off. Many people use both: herdr for local coding sessions, a hosted bot for the always-on assistant.