Run hermes chat -q "your prompt" --format stream-json and the Hermes CLI prints one JSON event per line to stdout — an init event, streamed text deltas, every tool call and tool result, then a final result record with token counts and an exit code — which is exactly what the new hermes agent stream json output mode is for: turning an agent run into machine-readable events any script, pipeline or dashboard can consume. The flag arrived with Hermes Agent v0.21.4, released 21 September 2026 as part of a patch that folded in roughly 1,800 merged pull requests, and it quietly solves one of the oldest annoyances in Hermes automation: parsing human-formatted terminal output with fragile regexes. Here is the exact syntax, every event type and field, the exit-code contract, and the automation patterns it unlocks.
📺 Watch: NEW Hermes Agent Update is ABSOLUTELY WILD!
🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside
The Exact Command and Its Rules
Per the official Hermes Agent CLI reference from Nous Research, the flag hangs off single-query mode: hermes chat -q "Summarise this repository" --format stream-json, or hermes chat --query-file path-to-prompt.txt --format stream-json when the prompt lives in a file. Three rules from the docs are worth committing to memory before you script against it. The flag requires -q (or --query, or --query-file) — it is for one-shot runs, not interactive sessions. It implies quiet, non-interactive mode, so nothing decorative pollutes the stream. And it rejects an explicit --tui, because a terminal UI and a machine-readable stream are mutually exclusive by design. The docs also pin down the stream contract in one sentence: every stdout line is one JSON object, while diagnostics and the session-id line stay on stderr. That separation is the whole point — stdout becomes a clean event feed you can pipe straight into jq, a log collector or a queue without filtering.
Hermes Agent Stream JSON Output: Every Event Explained
The CLI reference documents five event types, each stamped with a timestamp in Unix epoch milliseconds. In the order you will meet them in a typical run:
| Event type | Fields | When it fires |
|---|---|---|
| system (subtype init) | model, session_id | Once at start, telling you which model is serving the run |
| text | text | Each streamed chunk of the assistant's answer |
| tool_use | name, input when available | Every time the agent invokes a tool |
| tool_result | name, output capped at 5,000 characters, duration_ms, is_error | When that tool call returns |
| result | session_id, exit_code, text, token counts, duration_ms, error on failure | Once, as the terminal record of the run |
Source: Hermes Agent CLI commands reference, Nous Research documentation, September 2026.
The result event deserves a closer look because it is the record your automation should key on. It carries the full final text, the run's duration in milliseconds, and a token breakdown covering input, output, total, cache reads and cache writes — which means per-run cost tracking comes free with every invocation. The docs are explicit that once a conversation starts, the terminal record is always result, even when a run is interrupted, and that you should treat that record as the completion signal. Anyone who has built monitoring for agent fleets knows why that guarantee matters: a stream that always ends with a self-describing summary event is a stream you can supervise.
If you want ready-made Hermes automations that use exactly these patterns — plus the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls — join the AI Profit Boardroom here. Want 1-on-1 help wiring AI into your SEO workflow first? Book a free SEO strategy session and get it planned live.
Exit Codes: The Contract Your Scripts Rely On
Stream-json runs report their outcome twice — in the result event's exit_code field and in the process exit code, which the docs state always match. The mapping is short enough to memorise: 0 means the turn completed; 1 means it failed, stopped partway, hit its iteration budget, or never ran at all because credentials or agent initialisation failed; 130 means it was interrupted, the standard Ctrl-C convention. For automation this is the difference between guessing and knowing. A cron job wrapping a Hermes run can branch on the exit code alone: retry on 1, alert on repeated 1s, treat 130 as operator intervention and stand down. Combine that with the is_error flag on individual tool_result events and you can distinguish a run that failed outright from one that completed despite a flaky tool call along the way — a distinction that decides whether your pipeline retries the whole job or just logs a warning.
Automation Patterns Hermes Stream JSON Output Unlocks
Once every run is a stream of structured events, a set of workflow upgrades becomes almost trivial to build, ranked here by how much leverage they give you:
- CI and scheduled pipelines. The upstream pull request that shipped the feature describes it as CI-ready JSONL for one-shot runs — run Hermes on a schedule, pipe stdout to a file, and your pipeline gets a parseable transcript plus a truthful exit code instead of scraped terminal text.
- Cost dashboards. Collect the tokens block from every result event and you have per-task, per-day and per-workflow spend without touching a billing API. Feed it into anything that reads JSON lines.
- Tool-call auditing. The tool_use and tool_result pairs, with duration_ms on every result, show which tools your agent leans on and which ones run slow or error-prone — the raw material for trimming a bloated toolset.
- Chained agents. Because the final result event carries the complete answer text, one Hermes run's output can become the next run's query with a few lines of shell — no parsing heuristics, no lost formatting.
These patterns slot straight into the workflow style the Agent OS is built around — agents as composable, schedulable units rather than chat windows — and they pair naturally with the browsing and retrieval side covered in the Hermes Agent web search guide. For inspiration on what to automate first, the Hermes Agent use cases roundup lists the workflows readers most often wire up.
Where This Fits Among Hermes Interfaces
Stream-json is the third leg of how you drive Hermes, and knowing when to use each saves confusion. Interactive TUI and chat remain right for exploratory work, and the visual side keeps improving — the Hermes dashboard command guide covers the monitoring view added earlier in September 2026, the closest sibling to this feature on the human-facing side. The desktop app, covered in the Hermes desktop installation guide, is the fit for daily driving with a GUI. Stream-json exists for the third audience: no human watching at all. It is the mode you reach for when Hermes becomes a component inside something bigger — a build step, a nightly job, a webhook handler. The same v0.21.4 release rounded out that story with structured-output work elsewhere in the CLI, a new hermes sessions set-journal-mode command, and a dozen new community plugins, per the official release notes on GitHub — but the format flag is the piece that changes how Hermes composes with the rest of your stack. If you are still deciding how to run Hermes day to day, the Hermes Workspace vs Hermes Agent comparison maps the options, and the Workspace v2 write-up covers the hosted route.
A note on verifying model quality inside these automated runs: because the init event names the model serving each session, stream-json also gives you a clean audit trail of which brain handled which task — useful when you are routing between models, and the Goldie Bench write-up covers how those brains compare in hands-on tests when you need to pick.
Getting Started Today
Update to Hermes Agent v0.21.4 or later, run a single-query command with --format stream-json, and inspect the event stream with a JSON-lines viewer before wiring anything permanent. Confirm your wrapper keys on the result event and its exit code rather than parsing text events, keep stderr separate so the session-id line never contaminates your data, and remember the 5,000-character cap on tool_result output when a tool returns something huge. Within an afternoon you can take any Hermes workflow you currently babysit in a terminal and turn it into a scheduled, supervised, cost-tracked job — which is precisely the kind of compounding automation the hermes agent stream json output mode was shipped to enable.
One implementation detail that saves debugging time: because the docs specify that the final result event carries the complete answer text, your scripts never need to reassemble the streamed text deltas themselves — treat the text events as progress indication for anything a human might watch, and take the authoritative answer from the result record alone. That single decision removes an entire class of concatenation and ordering bugs from stream-json consumers, and it is the pattern the exit-code contract was clearly designed around.
If you want to skip the trial and error and copy working scheduled-agent setups — the AI Profit Boardroom includes the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls — check it out and get inside here. And if a personal 1-on-1 roadmap sounds better, book a free SEO strategy session now.
