hermes-superagent
Health Uyari
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 6 GitHub stars
Code Uyari
- network request — Outbound network request in assets/art/met_fetch.py
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
Hermes Agent plugin: one router in front of a worker per task, a watchdog that restarts the stuck ones, and a ledger that never drops an issue, task or Claude Code session
A plugin for Hermes Agent, Nous Research's AI agent, for when you run more agents than you can watch.
You message one coordinator (the router) in chat, and every task goes to its own isolated agent. A separate process restarts the ones that hang and tells you when it can't fix them. A ledger keeps every issue and task listed until its source confirms it closed, and puts every Claude Code session on one board. That part runs without Hermes.
Based on DeepSeek's Super-agent design.
Quickstart · Examples · Why · Architecture · Features · Install · Configuration · Comparison · Security · Roadmap · Contributing

Quickstart
One command and about ten seconds. No Hermes, model or credentials: only the agents and the source data are scripted. The gate, router, watchdog, ledger and SQLite store are the real code, and each worker is a real process. You need uv on macOS or Linux, and it fetches a newer Python if yours is too old.
uvx --from git+https://github.com/AirKyzzZ/hermes-superagent superagent-demo
No uv? With Python 3.11+, clone the repo and run python3 demo/run_demo.py. To point the ledger at your own GitHub issues, still without Hermes, go to Install.
Examples
Three more one-command runs, also with no credentials, each with a recording. They need a clone and Python 3.11+:
git clone https://github.com/AirKyzzZ/hermes-superagent
cd hermes-superagent
python3 examples/nothing-slips/run.py
python3 examples/night-shift/run.py
python3 examples/watchdog/run.py
- Nothing slips: four mornings across GitHub, Todoist, Gmail and WhatsApp, where a broken export and a deleted task don't lose anything.
- Night shift: six coding tasks handed off at night, and the one digest you read in the morning.
- Watchdog: five ways an agent gets stuck, and what catches each one.
Then on your own data, read-only through your gh login: python3 examples/your-github/run.py lists what's open on your GitHub and what has waited longest.
Why
DeepSeek's article puts the limit at three to five active sessions: past that, a person's attention runs out before the models do. Here you never manage sessions.
- Continuous: you talk to one router on the channels you already use.
- Efficient: each task gets its own worker, so a new request doesn't wait for an old one to finish.
- Proactive: events pass a gate on who sent them, then rules your team writes in plain language. A daily digest shows what each rule in record mode would have started, so you switch it to
actonly once it's right. - Persistent: state lives in SQLite, and a scheduled process outside the workers checks that the work is really moving.
- Nothing dropped: connectors read GitHub, GitLab, Todoist, Gmail, Google Calendar, WhatsApp, CodexBar, Anki, any tool that prints JSON, and every Claude Code session on your machines into a ledger, and triage rules file what comes in by area. An issue or task stays open until its source confirms it closed or you close it with a reason, and a daily brief shows each open one at least every few days.
A prompt or skill can only ask a model to stay in its lane, or to remember a task. Here the gate, the tool allowlist, fencing, the watchdog process and the ledger's completeness checks are code the model can't talk its way past or forget, which is why this has to be a plugin.
[!WARNING]
Early build. CI runs the router and worker path on real Hermes 0.22.7, 0.23.0 and 0.23.2 with a fake model: a webhook event goes through the real gateway and the gate to the router, the router dispatches, workers overlap, report, get guarded, fenced and stopped for real, and the watchdog relays the result to a stub. One recorded run on Hermes 0.23.0 and a real model wrote a worker brief, took one task through a real worker and the watchdog, and relayed the result to Discord withhermes send. That task came in throughsuperagent ingest, so no chat message has reached the router's model yet, and the watchdog's drift judge didn't fire. The watchdog's nudge, restart and escalate haven't run on real Hermes, and unit tests and the demo cover those three repairs. The Gmail, Google Calendar and WhatsApp connectors have only run on synthetic data. The ledger, its connectors and the agents board don't need a model, onlyhermes superagent briefsdoes.
Why not just...
- ...open more Claude Code tabs? Past three to five sessions you become the scheduler, and a session stopped by a rate limit waits until you happen to look. The agents board puts every session from every machine on one list and posts one line when one needs you.
- ...write a prompt or a skill? A skill can ask a model to stay in its lane and remember a task, it can't make it. The gate, the tool allowlist, fencing and the watchdog are code outside the model.
- ...rely on GitHub notifications and a to-do app? They show what's new, not what quietly disappeared. The ledger keeps an item open until its source confirms it closed, and lists every open one in the daily brief at least every few days.
- ...run a cron job that sweeps your tools? The ledger was built to replace exactly that. A sweep that misses a page or gets a cut list drops work without a word. Here a cut list or a total that shifts mid-scan marks nothing as gone and raises an alert by the third failed poll, and a snapshot that shrinks by half waits for you to accept it.
- ...use another orchestration plugin? nerve, agora and diaktoros are further along and each solves a different problem, see the comparison.
Architecture
The architecture page has the whole system on one map, who decides what, each phase of a tick and what happens when a part breaks. Here's the short version:
flowchart TB
people(["People on chat"])
events(["GitHub and other webhooks, superagent ingest"])
subgraph routerProfile["Router profile"]
gate(["Gate<br/>source and sender, never the text"])
router["Router<br/>talks and dispatches, never executes"]
end
workers@{ shape: procs, label: "Workers<br/>one session per task" }
store[("SQLite store")]
subgraph watchdogProfile["Watchdog profile, on a schedule"]
rules["Team rules<br/>record or act"]
watchdog["Watchdog<br/>progress and goal drift"]
relay["Relay<br/>code, no model"]
end
people -->|message| gate
events --> gate
gate -->|admitted| router
router -->|superagent_dispatch| workers
workers -->|superagent_report| store
gate -->|"candidates, thread follow-ups"| store
gate -.->|"addressed ingest event"| workers
store --> rules
store --> watchdog
store --> relay
rules -.->|"act: open a ticket"| workers
watchdog -->|"nudge, queued"| store
watchdog -.->|restart| workers
relay -.->|"reports, escalations"| people
relay ~~~ controlsClearance[" "]
classDef invisible fill:none,stroke:none
class controlsClearance invisible
%%{init: {"theme":"base","layout":"dagre","flowchart":{"wrappingWidth":420,"nodeSpacing":36,"rankSpacing":44},"themeVariables":{"primaryColor":"#1a10b8","primaryTextColor":"#ffffff","primaryBorderColor":"#a9a9cc","lineColor":"#8a8ab8","textColor":"#ffffff","clusterBkg":"#14142a","clusterBorder":"#4a4a78","titleColor":"#f4f4fd","edgeLabelBackground":"#14142a"}}}%%
On the gateway, the router's model only sees messages the gate let through, plus an allowed person's / commands that Hermes turns into a turn, such as skills. A webhook or superagent ingest event from an allowed sender skips that model: code opens the ticket, with the event text as the goal. In the documented setup workers have no messaging tools, so their reports go to the store and code relays them.
One task
sequenceDiagram
participant person as Person
participant gate as Gate
participant router as Router
participant store as Store
participant worker as Worker
participant tick as Watchdog tick
rect rgb(20, 20, 42)
person->>gate: fix the login redirect loop
gate->>store: record the admitted trigger
gate->>router: pass the message on
router->>store: superagent_dispatch(trigger, goal)
router->>worker: start with a brief and a fence token
loop until the task ends
worker->>store: superagent_report(progress)
tick->>store: check progress and goal drift
end
alt worker is blocked
worker->>store: superagent_report(blocked, question)
tick->>person: relay the question
person->>gate: answer
gate->>worker: in a thread, a new worker resumes with the answer
Note over gate,store: outside a thread, the router's model<br/>calls superagent_forward
else worker is done
worker->>store: superagent_report(ready, summary)
tick->>person: Done, in at most 100 words
end
end
%%{init: {"theme":"base","sequence":{"mirrorActors":false,"diagramMarginY":48},"themeVariables":{"primaryColor":"#1a10b8","primaryTextColor":"#ffffff","primaryBorderColor":"#a9a9cc","lineColor":"#8a8ab8","textColor":"#ffffff","actorBkg":"#1a10b8","actorBorder":"#a9a9cc","actorTextColor":"#ffffff","actorLineColor":"#8a8ab8","signalColor":"#a9a9cc","signalTextColor":"#ffffff","labelBoxBkgColor":"#0a0a9a","labelBoxBorderColor":"#a9a9cc","labelTextColor":"#ffffff","loopTextColor":"#ffffff","noteBkgColor":"#0a0a9a","noteBorderColor":"#a9a9cc","noteTextColor":"#ffffff"}}}%%
Watchdog
stateDiagram-v2
direction TB
[*] --> Running
Running --> Running: nudge queued
Running --> Restarting: dead with no output, or nudges spent
Restarting --> Running: fenced, new worker
Restarting --> Escalated: can't stop it
Running --> Escalated: budgets spent
Running --> Parked: blocked, or exited without reporting
Parked --> Running: answered
Running --> Ended: ready, failed, dropped
Escalated --> Ended: ticket closed
Ended --> [*]
classDef ended fill:#14142a,color:#ffffff,stroke:#a9a9cc
classDef alert fill:#f4f4fd,color:#14142a,stroke:#1a10b8
class Ended ended
class Escalated alert
%%{init: {"theme":"base","layout":"dagre","themeVariables":{"primaryColor":"#1a10b8","primaryTextColor":"#ffffff","primaryBorderColor":"#a9a9cc","lineColor":"#8a8ab8","textColor":"#ffffff","transitionColor":"#8a8ab8","transitionLabelColor":"#ffffff","stateLabelColor":"#ffffff","stateBkg":"#1a10b8","labelBackgroundColor":"#14142a","edgeLabelBackground":"#14142a","specialStateColor":"#8a8ab8","innerEndBackground":"#8a8ab8"}}}%%
Stuck and drifting lead to the same repairs, within a budget per ticket. Code decides stuck: a dead process, silence, identical reports or the same tool call over and over. A judge with no tools decides drift and can only answer on_track or drifting, so the most a fooled judge can do is spend the budget and escalate, which ends the ticket. A broken judge never triggers a repair.
A live worker gets a nudge first, and it waits for that worker's next report, so a silent worker gets restarted on the next tick instead. An escalation stops the worker if it can, then relay tells the person on a best-effort basis, and a reply starts new work. A worker that exits without reporting is parked for a person with its last output, so the task doesn't run twice, and only one that left no output is restarted.
Ledger
flowchart TB
sources(["GitHub, GitLab, Todoist, Gmail, Calendar, WhatsApp,<br/>CodexBar, Anki, any tool that prints JSON,<br/>Claude Code sessions over ssh"])
check{"Whole and plausible?<br/>no cut list, no shifting total,<br/>not shrunk by half"}
ledger[("Item ledger<br/>new, triaged, assigned, waiting,<br/>done or ignored, always with a reason")]
held["Nothing marked gone<br/>a shrunk snapshot waits for accept"]
vanished["Gone from its source<br/>checked one by one"]
out(["Daily brief, agents board,<br/>alerts"])
sources -->|"every poll"| check
check -->|yes| ledger
check -->|no| held
held -.->|alert| out
ledger -->|"missing from a snapshot"| vanished
vanished -->|"confirmed closed"| ledger
ledger --> out
%%{init: {"theme":"base","layout":"dagre","flowchart":{"wrappingWidth":420,"nodeSpacing":36,"rankSpacing":44},"themeVariables":{"primaryColor":"#1a10b8","primaryTextColor":"#ffffff","primaryBorderColor":"#a9a9cc","lineColor":"#8a8ab8","textColor":"#ffffff","clusterBkg":"#14142a","clusterBorder":"#4a4a78","titleColor":"#f4f4fd","edgeLabelBackground":"#14142a"}}}%%
A poll that fails a completeness check marks nothing as gone, and after three failed polls in a row the source shows as failing on the alerts channel and in the brief. An issue or task that disappears from a source is asked about by id, and only a closed answer closes it. Anything else stays open under "gone without a close" until someone decides. A Claude Code session that has ended, or been gone for an hour, closes by itself. The brief lists every open item again once stale_after has passed, unless it's snoozed or its worker is running, and that's tested on the text queued for delivery.
Features
| Routing | Workers | Watchdog and safety |
|---|---|---|
| A router that can't execute A pre_tool_call allowlist blocks everything else, and Hermes fails closed if the hook errors. |
One worker per task Its own session, directory and environment allowlist. send_message and cron are blocked, and the documented toolsets add no other messaging tool, so it reports through superagent_report. A terminal can still reach whatever its sandbox allows. |
An outside watchdog A separate scheduled process. It can nudge, restart or escalate within a budget, and can't edit rules or widen a task. |
| A gate blind to content Pure code over source, sender and bot lists. The message text can't open it. |
Thread pass-through A follow-up in a task's thread reaches its worker in its next report result, with no router model call. |
Fenced repairs Each worker has its own token. It's fenced before it's stopped, so a late report from an old worker is refused. |
| Rules that start quiet Team rules begin in record mode and only log what they would have done, until you set act. |
Parked, not lost A blocked task waits for an answer, then a new worker resumes with it. |
Inert until you opt in With no role set, outside a worker directory, its hooks do nothing and it offers no tools. |
| Sources | Sessions | Every day |
|---|---|---|
| A ledger that keeps everything Items are never deleted. Closing or ignoring one takes a reason, and every change is kept, each change at the source with the content it saw. |
An agents board A small hook on each machine and a read-only probe over ssh put every Claude Code session on one board: working, waiting, stuck, rate-limited, gone. |
A daily brief Source problems, what waits on you, what vanished, what reopened, what's new, and every other open item at least every few days. A box that was down catches up. |
| Sources that fail loudly GitHub and GitLab through your gh and glab logins, or any tool that prints JSON, with total or limit set to catch a cut list. A cut list, a total that shifts mid-scan or a snapshot that shrinks by half is held back, never read as done, and three failed polls in a row raise an alert. |
One line when one needs you A session waiting for you, stuck, rate-limited or gone for two polls posts one line to its channel, and one that had been quiet for an hour when it died just closes. Its text stays out unless you opt in, and it's redacted then. |
Alerts and an outbox that never gives up Messages retry with backoff and stay in order, until one has failed three times and stops holding up the rest. Lasting errors and stuck ticks are alerted, and a heartbeat lets an outside check notice a dead timer. |
Briefs that cite their sourceshermes superagent briefs <item> writes the brief a worker would start from, and every line names the piece it came from: the issue, the owner's comments, related items, where the code lives. |
Drafted, challenged, revised A second model call reads the draft like a skeptical senior engineer, and a third fixes what it found. |
A lint the model can't argue with A URL or command that only a stranger's comment or mail holds never reaches a brief marked ready, and untrusted text marks it NEEDS APPROVAL. |
Triage by plain rules[[triage]] rules file new items into areas, each with its own channel, or set them aside with a reason the brief shows. An item no rule matches stays new and keeps showing up. |
A nudge, only if you ask With relaunch = true, a session stopped by an API error or a rate limit gets one continue, typed only after its pane, process and screen check out. |
Setup and doctorsetup writes a starter config from the tools it finds, and doctor checks the delivery command, the timer and every connector, live, without recording anything. |
Install
Watch your sources and sessions
One profile is enough, with no role, so the plugin stays inert in chat:
hermes plugins install AirKyzzZ/hermes-superagent --enable
hermes superagent --home ~/superagent setup
hermes superagent --home ~/superagent doctor
No Hermes yet? Install the CLI on its own and run the same commands, and brief prints what's open instead of sending it. pip install git+https://github.com/AirKyzzZ/hermes-superagent works as well, and in a clone python3 -m superagent needs no install. With gh logged in, this lists your open issues, pull requests and review requests:
uv tool install git+https://github.com/AirKyzzZ/hermes-superagent
superagent --home ~/superagent setup
superagent --home ~/superagent doctor
superagent --home ~/superagent tick && superagent --home ~/superagent brief
setup writes a starter superagent.toml from what the machine has: a connector for each of gh, glab, td and codexbar it finds, and the agents board when Claude Code is there. It never overwrites a config, so to get failures on a channel, pass --alerts discord:<channel id> the first time, and it sends through the same hermes. doctor checks the config, the delivery command, the timer and alerts, runs each connector's poll once without recording anything, and exits non-zero when something fails. Then schedule the tick every 2 minutes:
(crontab -l 2>/dev/null; echo "*/2 * * * * PATH='$PATH' hermes superagent --home ~/superagent tick") | crontab -
Without Hermes, write superagent instead of hermes superagent in that line. The shadow install guide has a systemd timer, other machines and the Claude Code hook.
Run it with Hermes
Needs Hermes 0.22.7 or newer on macOS or Linux. These steps haven't been run end to end yet, see the warning above.
Setup stepsInstall and enable it in each profile, give each its role and the directory they share, and give the worker a sandbox:
mkdir -p ~/superagent
for p in router worker watchdog; do
hermes profile create "$p"
hermes -p "$p" plugins install AirKyzzZ/hermes-superagent --enable
hermes -p "$p" config set plugins.entries.hermes-superagent.settings.role "$p"
hermes -p "$p" config set plugins.entries.hermes-superagent.settings.home ~/superagent
done
hermes -p worker config set terminal.backend docker
Write ~/superagent/superagent.toml, with your own value for each YOUR_...:
[sources.discord]
policy = "explicit_only"
allow = ["YOUR_DISCORD_USER_ID"]
[worker]
argv = ["hermes", "-p", "worker", "chat", "-Q", "--query-file", "{brief}", "-t", "terminal,file,superagent"]
[outbound]
argv = ["hermes", "-p", "router", "send", "--to", "{channel}", "{text}"]
[[semantic]]
name = "silent-fix"
text = "Reproduce reported bugs quietly, speak up only with a confirmed fix."
mode = "record"
Keep gateway credentials out of the worker profile. Then take terminal and file away from the router on the platform it answers on, restart the gateway so it picks up the plugin's toolset, and schedule the watchdog:
hermes -p router tools disable --platform discord terminal file
hermes gateway restart
(crontab -l 2>/dev/null; echo "*/5 * * * * PATH='$PATH' hermes -p watchdog superagent tick") | crontab -
Every message names its task, as in Done [fix the login redirect · tk-1a2b]: …, so replies can't get mixed up. To stop a task, tell the router, or run hermes -p watchdog superagent cancel <ticket>. Questions, results, failures and escalations reach people on the next tick. Progress stays in the store. A worker is whichever session runs in its own worker directory, so the worker profile refuses any other session and isn't for general chat.
Hermes defers plugin tools behind tool_call by default, and that works. Set tools.tool_search.enabled: off in a profile to hand its model the tools directly.
To take work from GitHub, add a route to Hermes's webhook platform in the default profile's config.yaml, merged into its platforms: key if it has one, with the secret you set on the GitHub webhook:
platforms:
webhook:
enabled: true
extra:
routes:
github:
secret: "YOUR_GITHUB_WEBHOOK_SECRET"
events: ["issue_comment"]
filters:
- field: "action"
equals: "created"
prompt: "Handle this comment on {repository.full_name}#{issue.number}: {comment.body}"
profile: router
Then say who may start work from it in superagent.toml:
[sources."webhook:github"]
policy = "explicit_only"
allow = ["YOUR_GITHUB_LOGIN"]
notify = "discord:YOUR_CHANNEL_ID"
The rendered prompt becomes the goal, the comment's author is checked against allow, and the issue becomes the task's thread, so later comments from allowed people reach the running worker. Results go to notify. Keep a real secret on the route: Hermes checks GitHub's signature with it, and without one anyone who can reach the route can claim to be any author.
Configuration
superagent.toml lives in the shared directory, and edits to its rules apply without a restart. Unknown keys and values of the wrong type are refused. If an edit is refused, for bad TOML, an unknown key, a wrong type or a missing value, the plugin keeps running on the last good copy while every tick fails with the error until it's fixed. Hermes gives hooks no mention flag, so chat messages always count as addressed, and team rules only see listed bots and ingest events for now.
| Key | Default | What it does |
|---|---|---|
[sources.<name>] policy |
required | explicit_only, candidate or ignore |
[sources.<name>] allow |
[] |
People who may address the agent |
[sources.<name>] bots |
[] |
Bots whose events can become candidates on a candidate source |
[sources.<name>] pass_strangers |
false |
Lets strangers' thread messages reach a worker, framed and with no authority |
[sources.<name>] notify |
none | Channel that gets this source's results and escalations instead of the event's own, such as discord:123 |
[sources."webhook:<route>"] via_router |
false |
Lets the router's model read this webhook's admitted events instead of starting work directly. Authors still go through allow |
[[semantic]] name, text |
required | A team rule, written in plain language |
[[semantic]] mode |
record |
record only logs, act opens a ticket |
[worker] argv |
required for workers | Command for one worker, must reference {brief} |
[worker] allow_same_user |
false |
Allows host tools in a worker with no sandbox |
[worker] max_running |
0, no cap |
How many workers run at once. A task past the cap waits in a queue, says so once on its channel, and starts on the first tick after a worker finishes, oldest first. New work waits behind tasks already queued, and nothing starts from the queue without the tick. A restarted worker keeps its own slot, and a waiting task is never treated as stuck |
[outbound] argv |
none | Delivery command using {channel} and {text}. Without it nothing is sent, and messages are still marked sent. A failed send fails every tick until it gets through. Retries back off up to 30 minutes and never give up, and superagent outbox lists what's waiting or drops a message for good. Messages over 1900 characters go out in numbered parts |
[digest] channel |
none | Where superagent digest --send and the daily digest blueprint deliver |
[channels] alerts |
none | Where alerts go. An alert is sent when a tick error has lasted alert_after_seconds, and "Resolved" follows once it has stayed clear as long. A tick stopped at its deadline, one stuck holding the lock, or a source warning is alerted at once. With no channel set, an alert waits for one for as long as its problem lasts |
[tick] deadline_seconds |
600 |
A CLI tick running longer is stopped. A tick that finds the lock held longer than this fails loudly instead of skipping |
[tick] alert_after_seconds |
300 |
How long a tick error has to last before it's alerted |
[heartbeat] argv |
none | Runs after every tick with no errors, such as a ping to an external uptime check, so a dead timer gets noticed from outside |
[channels] brief, [brief] hour, timezone |
none, 8, UTC |
The daily brief goes to brief once a day, from hour until the next day's hour, so a box that was down catches up. It lists source problems, what waits on you, what vanished from a source, what reopened, what's new since the last brief, what got ignored and why, and the day's readings. Every other open item shows at least once every stale_after, unless it's snoozed or its worker is running. "Since the last brief" only moves once every part of that brief has been delivered. superagent brief prints it now, and --send queues it for the next tick instead |
[brief] stale_after |
3d |
How long an open item can go unlisted before the brief lists it again |
[[triage]] match, area, ignore, name |
match and one of area or ignore required, name is the rule's number |
Rules for new items, the first match wins. match maps item fields (connector, title, url, id, due, excerpt) or meta keys such as repo, labels or from to a glob or a list of globs, ignoring case, where only * and ? are wildcards. labels, matched and tags match on any one of their comma-separated parts, and an empty field never matches. area files the item there as triaged, and ignore sets it aside with that reason, which the next brief lists. An item no rule matches stays new and comes back every stale_after until someone decides. Rules also file new items already in the ledger, and never touch one that isn't new |
[areas.<name>] channel |
none | Where one "New in " message per tick lists what rules filed there, up to 20 items. Once any area is listed, rules can only name listed areas |
[channels] briefs, [briefs] notes, repos, daily_limit |
none, none, none, 20 |
hermes superagent briefs <item> writes the brief a worker would start from. Code builds a pack of numbered pieces, each marked trusted or not: the item, for GitHub items its issue text and comments (only the owner's own are trusted), related ledger items, its history, notes, and where repos says the code lives (keys are owner/repo for GitHub and gitlab:group/project for GitLab). The model drafts, a second call challenges it as a skeptical senior engineer, and a third revises. Code then checks that every line cites a real piece, quotes match their piece, there's an acceptance criterion, nothing looks like a secret, and every address, host, IP, account, shell command and multi-word code span appears in trusted text, after undoing lookalike characters. The first line says READY, NEEDS APPROVAL when any piece is untrusted, or NOT READY with the lint's findings at the end. A quote in the owner's own comment stays untrusted, and so does anything posted through an app. Briefs are cached until the pack or the writer changes, daily_limit caps new ones with failed attempts included, and --send posts it to briefs |
[connectors.<name>] type |
required | command, github, gitlab, todoist, gmail, gcal, whatsapp, codexbar, anki or agents. A connector polls one tool into the item ledger. docs/connectors.md has a copy-paste block for each |
[connectors.<name>] every |
5m |
How often it polls |
[connectors.<name>] track |
true |
false keeps its items, such as readings or events, without anyone owning them |
[connectors.<name>] quiet_after |
off, required for delta sources | Warns when the source has had nothing new for this long |
command: argv, fields, items |
argv and fields required, items is the top-level list |
Runs argv and reads its JSON. items is the dotted path to the list. fields maps id, title, url, due, status, excerpt and any extra meta key to a dotted path or a {path} template. A bad item fails the run but the good ones are still recorded, and a mapped path that no item has fails it too |
command: total, limit |
none | Catch a cut list: total is the path to the count the tool reports, which must match, and a run that returns limit items or more fails |
command: complete, confirm_argv |
true, none |
A complete source returns everything open each time, so items it stops returning are marked gone. A snapshot that shrinks by half or more, from 5 items up, is held back until superagent ledger accept <name>. confirm_argv with {id} checks one vanished item's status. An id that starts with a symbol or holds anything outside letters, digits and ._:/#@+=- is never passed to it |
command: env, timeout, closed |
none, 60, closed, done, completed, true, merged |
Variables passed through to the command, its timeout (the whole process group is stopped), and the status values that mean closed |
command: complete = false, overlap, backfill |
true, 10m, 14d |
A delta source gets {since} (UTC, 2026-11-05T22:00:00Z), {since_epoch} or {since_date} (2026/11/05) in its argv. It starts backfill ago and each window reaches overlap back into the previous one |
[connectors.<name>] announce_new |
false |
Posts one message per poll to the connector's channel, which it requires, listing the items that source showed for the first time, up to 20. A source's very first poll stays quiet |
[connectors.<name>] trusted |
false |
Marks a source as the owner's own words, such as a personal task list, so briefs treat its items as trusted. Refused on github, gitlab, gmail, gcal, whatsapp and agents, where the text can come from someone else |
[connectors.<name>] owned, channel, notify, notify_detail |
false, none, none, false (agents: true, none, waiting, stuck, limited, gone, false) |
Owned items start as the owner's instead of new. When an item's state has been one in notify for two polls, one line goes to channel. It names the item and its state, and adds its redacted text only with notify_detail |
agents: host, stall_after, python, timeout |
this machine, 20m, python3 over ssh, 30 |
Reads every Claude Code session active in the last 7 days on a host from the hook's logs, over ssh when host is set, and turns each into an item with its state: working, waiting, stuck, limited, background, idle, gone or ended. superagent agents prints the board. Setup is in the shadow install guide |
agents: relaunch, nudge, retry_after, tmux, cmux |
false, continue, 10m, tmux, cmux |
Off by default, because it types into your terminals. When on, a session that stopped on an API error gets one nudge after retry_after, and one stopped by a rate limit gets it only once Claude Code says its own auto-resume went stale. Before typing, a script on the host checks that the session hasn't moved, that its claude process is alive and in the foreground of that tmux pane or cmux surface, that no other live session shares the pane, that the pane isn't scrolled back, synchronized, dead or ignoring input, and that the last line between two rules on screen is the empty prompt, with no dialog, vim mode, interruption or work in progress. In tmux the pane state is checked again inside the same server command that types, and in cmux the process must be in the foreground of that surface. Each session gets one nudge, and an attempt that times out counts. Every attempt is in ledger show, and anything held goes to the connector's channel as needing you. A session whose process died is never restarted for you: its line carries the claude --resume command |
github: queries, gh, timeout, env |
assigned, review requested and mentioned, gh, 120, none |
Searches GitHub through gh api with your existing gh login. Each query must include is:open. Every page is read in creation order, the total must hold across pages and match the distinct items returned, and results that GitHub hides behind SSO fail the query. A failing query still lets the others' items in, but marks nothing gone. timeout covers a whole poll. Issues that leave every query are checked one by one, and only a closed one is closed |
gitlab: queries, glab, hostname, timeout, env |
assigned issues, assigned merge requests, review requests and pending todos, glab, none, 120, none |
Reads GitLab through glab api with your existing glab login, run from / so a checkout's remote can't switch the host. Each query reads issues, merge_requests or todos and must ask for exactly state=opened (todos: state=pending), and {me} stands for your username. Every page is read, and the total GitLab reports must hold across pages and match the distinct items returned, except for todos GitLab hides from the list after counting them. Each todo is its own item, closed once GitLab lists it as done, and an assignment or review todo is skipped only when this poll's issue or merge request query returned its target or failed. Issues and merge requests that leave every query are checked one by one, only a closed or merged one is closed, and one that moved to another project is reported |
todoist: td, timeout, env |
td, 120, none |
Reads every open task in every project, subtasks included, with td task list --all --json --full through your existing td login, and project names with td project list --all --json. A list td cuts before its last page fails the poll. Each task keeps its project, labels, priority, due date and deadline, and who added it, and a recurring task keeps its rule, such as every day, so ticking off one occurrence changes nothing. A failed project list records nothing that poll. A task that leaves the list is looked up with td task view, and only a completed one is closed. TODOIST_API_TOKEN is passed through, so a token works where td auth login can't run |
gmail: account, query, gog, timeout, env |
required, in:inbox, gog, 180, none |
One block per mailbox. Reads every thread query matches through gog, always with --readonly and --all pages, so a page that fails fails the poll, and the count must match the distinct threads. query must include in:inbox. Each thread keeps its sender, labels and message count, and reading a mail changes nothing. A thread that leaves the inbox is looked up, and only one with no INBOX label left, archived or trashed, is closed. Category filters belong in triage rules, so what they set aside is listed with a reason. gog fetches every thread's details each poll, so an inbox of a few thousand threads can outrun timeout; a narrower query such as in:inbox newer_than:90d keeps it in time, but a thread that leaves the query while still in the inbox then stays open under "gone without a close" until you close it |
gcal: account, calendars, days, gog, timeout, env |
required, the ones shown in Google Calendar, 3, gog, 120, none |
One block per account. Informational, so track is off, and it can't be trusted because anyone can send an invite. Reads days days from today through gog, always with --readonly and every page, one calendar per call so one that fails fails the poll. calendars takes ids or primary. Times are in the primary calendar's timezone. Titles carry the date, such as Mon 09 Nov 14:00 Dentist or ongoing until Thu 12 Nov Conference, and a days_away in the meta that changes daily lists an event in each brief until it's over. Events you declined and working locations are left out, a meeting on two calendars shows once, and an event leaving the window closes nothing |
codexbar: providers, codexbar, timeout, env |
the ones enabled in CodexBar, codexbar, 120, none |
One reading per provider from codexbar usage --format json, titled with its quota, such as claude: Weekly 21%, and keeping each window's reset time and any cost in its meta. Informational, so track is off. A provider that reports an error fails the poll and the others still record, so name only the working ones in providers if one stays broken. all and both are refused because most providers aren't set up. codexbar can be a list, such as ["ssh", "mac", "/opt/homebrew/bin/codexbar"], when it lives on another machine. Use every = "1h", since every change is a ledger entry |
anki: url, curl, timeout, env |
http://127.0.0.1:8765, curl, 60, none |
One reading per day of the cards Anki says are due (is:due), through the AnkiConnect add-on, using only findCards, getDecks and getNumCardsReviewedToday, such as Anki Mon 09 Nov: 54 due, 15 reviewed, with the count per top-level deck in its meta. New cards aren't counted, and neither are daily limits, so the number can differ from Anki's own. Informational, so track is off. Anki being closed, or its collection being unavailable, records nothing and isn't a failure, so add quiet_after = "3d" to hear about it. curl can be a list, such as ["ssh", "mac", "curl"], when Anki runs on another machine |
whatsapp: chats, sync, sync_max_age, activity_max_age, wacli, timeout, env |
required, follow, 30m, 6h, wacli, 120, none |
Watches the chats listed by JID through wacli, always --read-only. A chat is an item while the last thing said in it isn't yours, and it closes once you reply. Your reactions, calls, poll votes and empty rows never count as a reply, their call counts as reaching out, and reading changes nothing. Every poll first asks wacli doctor: a store that isn't linked, or whose sync isn't running or has heard nothing for activity_max_age (sync = "follow"), or hasn't run within sync_max_age (sync = "once"), fails the poll. In a group chat anyone's message counts, so list groups only when that's wanted |
[watchdog] stall_after_seconds |
900 |
Silence that counts as stuck |
[watchdog] repeat_limit |
3 |
Identical reports in a row that count as stuck |
[watchdog] repeated_call_limit |
5 |
Identical tool calls and results in a row that count as stuck |
[watchdog] nudge_budget |
1 |
Nudges per ticket, reset when a person's answer resumes a parked ticket |
[watchdog] restart_budget |
1 |
Restarts per ticket, reset when a person's answer resumes a parked ticket |
[watchdog] orphan_after_seconds |
30 |
How long an open ticket can go without a worker before a repair |
[watchdog] reap_grace_seconds |
30 |
How long a finished worker can linger before it's stopped |
Plugin settings and surface
Settings, tools and hooksSettings go under plugins.entries.hermes-superagent.settings in each profile's config.yaml.
| Setting | Values |
|---|---|
role |
router, worker, watchdog or empty. Empty keeps the plugin inert outside a worker directory |
home |
Directory shared by all three profiles, holding superagent.toml and the database |
| Tool or hook | Used for |
|---|---|
superagent_dispatch |
Router opens a ticket from an admitted trigger |
superagent_forward |
Router passes a follow-up to a running or parked ticket, resuming it |
superagent_cancel |
Router stops a ticket when someone admitted in its conversation or the person who started it asks, and tells them |
superagent_status |
Router or watchdog lists live tickets |
superagent_report |
Worker reports progress, blocked, ready, failed or dropped |
superagent_tick |
Watchdog assesses candidates, checks workers and relays |
superagent_digest |
Watchdog summarises recent work, waiting questions and what record-mode rules would have started |
pre_gateway_dispatch |
Runs the gate before Hermes handles a message, fails closed |
pre_llm_call |
Hands the router's model the admitted trigger ids |
pre_tool_call |
Enforces each role's tool policy |
post_tool_call |
Records worker activity for the watchdog |
hermes superagent setup writes a starter config and doctor checks a running one. hermes superagent briefs <item> writes a worker brief for one ledger item, and briefs --compare past.json --out sheet.md --key key.md sets new briefs beside the ones that ran for a blind comparison, see the dogfood design. hermes superagent ledger list, show, close, ignore and snooze work on the item ledger, which keeps every item a source shows until someone closes it with a reason. Connectors fill it, see [connectors] above and the dogfood design.
Comparison
These are three of the closest plugins in the Hermes catalog. Each solves a different problem, and all three are further along.
| hermes-superagent | nerve | agora | diaktoros | |
|---|---|---|---|---|
| Version | 0.1.0, not in the catalog | 0.4.15 | 2.0.13 | 0.5.0 |
| Built for | One agent in front of any work | Supervising agent turns and Kanban work: evidence, token spend, context | A role-based dev team that debates, votes and builds | Unattended pull request review and fixes, plus issue triage and CI repair |
| Who you talk to | A router that can't execute | Your usual Hermes agent | Your usual Hermes agent, with a leader chairing the team | Nobody, GitHub events drive it |
| Unit of work | One worker session per ticket | A Kanban card, on a local or SSH worker | A Kanban task for a role | A pull request |
| What starts work | Chat and ingested events, through a sender gate and team rules | Kanban cards | A project you start, then leader heartbeat and discussions | GitHub events |
| Progress check | Separate scheduled process: liveness, silence, repeats, goal drift | Hooks in a local worker, a controller-side bridge for SSH workers: locked definition of done, evidence, token checkpoints | Leader wakes on a cron to assess and unblock | Scheduled watchdog reports stalls, drains queued work and repairs routes, review rounds are capped |
| When stuck | Nudge, restart, escalate | Continue, watch, replan, block | Leader unblocks or raises a discussion | Reports it, disputes go to an adjudicator |
| Requires | Hermes 0.22.7+, macOS or Linux, a running gateway, a scheduler, a sandbox for worker tools | Hermes 0.21+, an API key for the default hosted backend | Hermes 0.20+, a running gateway | Hermes 0.21.5+, Linux, bubblewrap, three GitHub accounts, an HTTPS-reachable gateway |
Use nerve to gate Kanban completion on verified evidence, agora for a team that argues before it builds, and diaktoros for PR review. This one aims at a single agent in front of everything, and it's the least mature of the four. What we didn't find in these three is the combination: a resident router barred from executing in code, a trigger gate that ignores message text, and a tool-less judge checking each worker against its original goal from a separate scheduled process.
Based on each project's README and catalog entry at its pinned catalog commit and, for nerve's SSH path, its code, checked 2026-11-05.
Security model
Event content is attacker-controlled, so who can start or steer work is enforced in code. Framing is a second layer that depends on the model, and an act rule lets a model reading event text open a ticket.
[!CAUTION]
The boundary is the sandbox. A worker on a local terminal backend runs as your OS user and could rewrite the router's config, so the plugin refuses itterminal, file and code tools unless its profile uses a sandboxed backend such as docker or you setallow_same_user. Agents outside Hermes that use the report command get no such guard. Hermes runs every profile's turns in one gateway process by default, so profiles scope config and credentials, not the OS process.
| Threat | Control |
|---|---|
| Prompt injection through a trigger | The gate never reads message text. Dispatch only accepts a trigger the gate admitted, offered within the hour, still allowed and unused |
| Router tricked into executing | pre_tool_call allowlist, plus toolsets you remove from the profile |
| Stranger steering a worker | Bots never reach workers. Strangers don't either unless a source opts in, and a stranger can't resume a parked ticket |
| Forged or late reports | Per-assignment token, hashed in the database and handed over in a private file in the worker's directory. A session anywhere else gets no tools, and a worker is fenced before it's stopped |
| A report exfiltrating files | Relay is code. MEDIA: tags are neutralised and text is capped at 100 words |
| Watchdog fooled | The judge has no tools and returns one of two values, so the most it can do is spend the repair budget and escalate |
If the gate itself fails, the message is dropped and logged, so a person gets silence rather than a bypass. An allowed person's / commands skip the gate and go straight to Hermes unrecorded, even on an ignore source. They can reach the model as skills but can't start work, because dispatch needs a recorded trigger. The full threat model, with residual risks and known limits, is in DESIGN.md.
What it does on your machine
- Runs commands you configure: one worker process per task from
[worker] argv, with a fixed environment allowlist, the delivery and heartbeat commands with your environment, and each connector'sargvon its schedule during ticks, with a small base environment, the tool's own token if set, and the variables you list. Workers keep running after the turn that started them. - Stops processes: the watchdog signals its own workers' client process groups, which cancels their turns, and checks each start time first so a reused PID isn't hit.
- Types into a terminal only if you turn it on: with
relaunch = true, an agents connector types itsnudge(letters, digits and basic punctuation only) into a Claude Code session stopped by an API error or a rate limit, once per session, after the checks above. - Reads your sessions: an
agentsconnector runs a read-only probe script through thehostcommand you configure, usuallyssh, which reads the hook's logs and the process list. The hook is printed bysuperagent agents --hook-scriptand you install it yourself. It appends one redacted line per Claude Code event under~/.superagent/sessions, never blocks a session and keeps only an allowlist of pane variables from the environment. - Spends model tokens: ticks call the watchdog profile's model through
ctx.llmwhen there's a new report to judge or a candidate event to assess, andhermes superagent briefsmakes three calls per new brief, six at most with retries, withindaily_limit. Router and workers use their own profiles' models as usual. - Writes files:
superagent.db, a lock file, a last-good copy of the config and per-worker directories underhome, each with a brief, a private identity file and the worker's log, and it readssuperagent.tomlfrom there. - Leaves approvals to Hermes: workers start non-interactively from an environment allowlist, so they inherit no YOLO or approval-bypass setting. Hermes's approval rules apply to them as usual, which means that in a sandbox with no host mounts Hermes skips its dangerous-command prompts and the sandbox is the boundary.
- Doesn't: open network connections in its own code, send telemetry, or store your accounts' credentials. Connectors go through your tools' own logins, and
ankiposts to AnkiConnect throughcurl. The scripts inassets/artthat fetched the source image are build tools the plugin never runs.
Roadmap
- Router, one worker per ticket, gate, record-only rules, thread pass-through
- External watchdog with nudge, restart and escalate
- Guard hooks, runnable demo, CI against real Hermes discovery
- Workers proven end to end on real Hermes with a fake model
- Cancel on request, and a task label on every message
- A daily digest, including what record-mode rules would have done
- The router's path from a webhook through the gateway to relay, proven the same way
- First recorded run on a real model, see the transcript
- A real chat message through the router on a live model
- GitHub and other webhook sources
- Item ledger with GitHub and command connectors, source health and a daily brief, see the dogfood design
- Agents board for Claude Code sessions on several machines
- GitLab issues, merge requests and todos, and triage rules with areas
-
setup,doctor, and an offline demo of the ledger - Todoist through the
tdCLI, with new tasks flagged every poll - Gmail and Google Calendar through
gogand WhatsApp throughwacli, tested on synthetic data so far - Worker briefs written from the ledger's context, challenged and linted
- Nudging sessions stopped by API errors or rate limits, off by default
- Claude Code workers on tmux and cmux over ssh
What's next, and the connectors that need someone, are in ROADMAP.md.
Contributing
Issues and pull requests are welcome, new connectors most of all. Many tools need no code: a command connector reads anything that prints JSON. CONTRIBUTING.md has the setup, the checks CI runs and how to add a connector.
uv run --no-project --with-requirements requirements-dev.txt pytest -q
uv run --no-project --with-requirements requirements-dev.txt ruff check .
uv run --no-project --with-requirements requirements-dev.txt ruff format --check .
uv run --no-project --with-requirements requirements-dev.txt mypy
Design notes and the module mapping to Hermes are in DESIGN.md.
Credits
- Design: the DeepSeek Harness Team's article (in Chinese, with an unofficial, unreviewed translation) and their MIT-licensed research prototype. This is an independent Python implementation that copies no code from it.
- Host: Hermes Agent by Nous Research. This project isn't affiliated with DeepSeek or Nous Research.
- Art: Briareus, the Hundred-Handed. The head is the Marble head of Zeus Ammon, The Metropolitan Museum of Art, 2012.22 (public domain). The arms and hands are procedural. See assets/CREDITS.md.
If it's useful to you, a star helps other Hermes users find it.
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi