Hermes Agent (NousResearch/hermes-agent)
Produced by the ACP product case-study pass (2026-07-30), then adversarially verified; corrections below override the body where they conflict.
Hermes Agent (NousResearch/hermes-agent) - ACP case study
Hermes Agent is Nous Research's self-improving, self-hosted personal AI agent (CLI, TUI, messaging gateway, Electron app), MIT licensed, ~211k+ stars. This dossier focuses narrowly on the ACP client boundary.
1. ACP status
Hermes implements ACP natively, as an agent (server) exposed to editor/host clients. The implementation lives in the acp_adapter Python package inside the main repo, not a separate crate or fork. It depends on the official Zed-originated Python SDK agent-client-protocol (PyPI: https://pypi.org/project/agent-client-protocol/, docs at agentclientprotocol.github.io/python-sdk, repo github.com/agentclientprotocol/python-sdk), pinned in pyproject.toml as agent-client-protocol==0.9.0 under the optional [acp] extra. Current PyPI latest is 0.11.1, so Hermes trails the SDK by a few minor versions; the adapter also explicitly requests use_unstable_protocol=True in its boot call, signalling the maintainers know they are riding a protocol still settling. Maturity reads as production-supported (documented install path, troubleshooting section, VS Code/Zed/JetBrains/Buzz integration guides) rather than experimental, though there is no explicit "stable" designation. A GitHub tracking issue for this feature (#569, opened 2026-03-07) remains open and unclosed despite the feature having shipped, which is a stale-issue-hygiene artifact, not evidence of non-implementation, confirmed by reading the live pyproject.toml, the acp.md and acp-internals.md docs pages, and the [acp] script entry hermes-acp = "acp_adapter.entry:main" directly from the repo.
2. Integration wiring
Process model: stdio subprocess. A host (editor, Buzz's buzz-acp bridge, or in principle trogonai) spawns hermes acp and speaks JSON-RPC over stdin/stdout; Hermes routes all human-readable logs to stderr to keep the transport clean. HermesACPAgent (acp_adapter/server.py) wraps the existing synchronous AIAgent core, running it in a ThreadPoolExecutor and bridging callbacks back to the asyncio ACP loop via asyncio.run_coroutine_threadsafe. Session lifecycle: new_session(cwd) creates a SessionState plus an AIAgent(platform="acp", enabled_toolsets=["hermes-acp"]); sessions are tracked in-memory by a thread-safe SessionManager; fork_session() deep-copies history; cancel() sets a cancel event and calls agent.interrupt(). Notably, ACP list/load/resume/fork are scoped only to the currently running ACP server process, even though the underlying AIAgent still persists to Hermes' shared ~/.hermes/state.db. Permission requests map three ACP tiers (allow_once, allow_session, allow_always) plus deny onto Hermes' own approval semantics, with deny-by-default on timeout. MCP passthrough exists in a specific, asymmetric way: Hermes starts every globally configured MCP server from config.yaml before entering the ACP loop by default; a host can skip only that global startup via HERMES_ACP_SKIP_CONFIGURED_MCP=1, while MCP servers passed explicitly through session/new are always registered regardless.
3. Channel mapping
ACP is editor/IDE-scoped, not the mechanism for Hermes' messaging channels. Telegram, Discord, Slack, WhatsApp, and Signal are handled by a separate gateway platform process with its own per-platform code, entirely independent of ACP; see channel mapping for the general pattern. Hermes documents three distinct programmatic surfaces side by side (ACP, a TUI-gateway JSON-RPC protocol, and an OpenAI-compatible HTTP API), all driving the same AIAgent core but chosen based on transport needs, not layered on top of each other. One non-editor case does ride ACP: Buzz, a Nostr-based agent collaboration platform, ships a buzz-acp harness that spawns hermes acp as a subprocess and bridges a relay WebSocket to ACP stdio, explicitly documented as "a transport integration, not a second Hermes installation."
4. Callability from trogonai today
Yes, callable today via trogonai's existing acp-nats-stdio pattern, the same way it would spawn Claude Code or Gemini CLI. Install hermes-agent[acp] (pulls agent-client-protocol==0.9.0), configure a model provider via hermes model or ~/.hermes/.env, verify with hermes acp --check, then spawn hermes acp (or hermes-acp) as the ACP-side subprocess. No OAuth/device flow gates ACP itself; auth is whatever LLM provider credential Hermes already holds. Headless viability is real but risky by default: the hermes-acp toolset includes unrestricted terminal and execute_code, and Hermes' own docs warn that unattended hosts (Buzz Desktop) auto-approve these with allow_once, running shell commands with zero human check, including a documented rm -rf incident. Any headless trogonai integration must supply its own permission gate rather than trust Hermes' default tiers; see secrets at spawn and permission decision point. MIT license imposes no constraint.
5. Design lessons
Copy: the three-surface split (ACP for editors, a separate JSON-RPC gateway for rich custom hosts, HTTP/SSE for OpenAI-compatible clients) cleanly matches transport to consumer instead of forcing everything through one protocol. The explicit allow_once/allow_session/allow_always three-tier approval model, with allow_session as a well-reasoned middle ground, is a stronger UX than binary allow/deny. Avoid: process-local session scoping under ACP (losing list/load/resume across restarts despite full persistence existing underneath) is a real gap trogonai should not replicate if it wants durable, resumable ACP sessions. Also avoid silent unattended tool-approval defaults; Hermes' own docs concede this is a live footgun rather than a solved problem.
Sources
- https://github.com/NousResearch/hermes-agent
- https://raw.githubusercontent.com/NousResearch/hermes-agent/main/website/docs/user-guide/features/acp.md
- https://raw.githubusercontent.com/NousResearch/hermes-agent/main/website/docs/developer-guide/acp-internals.md
- https://raw.githubusercontent.com/NousResearch/hermes-agent/main/website/docs/developer-guide/programmatic-integration.md
- https://raw.githubusercontent.com/NousResearch/hermes-agent/main/pyproject.toml
- https://pypi.org/project/agent-client-protocol/
- https://api.github.com/repos/NousResearch/hermes-agent/issues/569
- https://api.github.com/repos/NousResearch/hermes-agent
Adversarial verification
- confirmed: ACP status is native via acp_adapter package (hermes acp / hermes-acp / python -m acp_adapter), SDK agent-client-protocol==0.9.0, extra hermes-agent[acp] (Verified verbatim in raw pyproject.toml (acp = ["agent-client-protocol==0.9.0"], hermes-acp script entry) and website/docs/user-guide/features/acp.md at raw.githubusercontent.com/NousResearch/hermes-agent/main.)
- refuted: Callability verdict yes: trogonai's acp-nats-agent/acp-nats-stdio bridge can spawn hermes acp as a stdio subprocess exactly like Claude Code, Gemini CLI, codex-acp it already targets (Inspected acp-nats-agent, acp-nats-stdio, acp-nats crates on trogonai main (commit 058b8bee): no Command::new/tokio::process subprocess-spawn code exists; acp-nats-stdio reads ACP JSON-RPC on its own stdin/stdout and bridges to NATS (agent side), not a client host spawning named external agent binaries, so the 'exactly like ... it already targets' framing is unsupported by the code.)
- confirmed: Prereqs for ACP mode: pip install hermes-agent[acp], configured provider via hermes model or ~/.hermes config, hermes acp --check to validate (All three steps documented verbatim in website/docs/user-guide/features/acp.md (Installation, Configuration and credentials, Troubleshooting sections).)
- confirmed: use_unstable_protocol=True and SDK pinned to 0.9.0 while spec/SDK has moved to 0.11.x (acp.run_agent(agent, use_unstable_protocol=True) appears verbatim in acp-internals.md boot flow; PyPI JSON for agent-client-protocol shows current version 0.11.1 with 0.9.0 present in release history.)
- confirmed: agent-client-protocol is the official Zed-originated Python ACP SDK documented at agentclientprotocol.github.io/python-sdk and github.com/agentclientprotocol/python-sdk, currently 0.11.1 (PyPI JSON project_urls exactly match (Documentation and Repository fields); version field is 0.11.1.)
- confirmed: Session lifecycle details: new_session binds cwd/creates AIAgent(platform='acp', enabled_toolsets=['hermes-acp']); prompt() uses ThreadPoolExecutor bridged via asyncio.run_coroutine_threadsafe; cancel() sets cancel event and calls agent.interrupt(); fork_session() deep-copies history (All details appear verbatim in acp-internals.md Session lifecycle and Cancelation/Forking subsections.)
- confirmed: Permission bridge maps allow_once/allow_session/allow_always/deny onto once/always/deny; timeouts and bridge failures deny by default (Confirmed in acp-internals.md permission bridge mapping and acp.md's approvals table; 'Timeouts and bridge failures deny by default' is a direct quote from acp-internals.md.)
- refuted: Session state is adapter-process-local: list/load/resume/fork only cover sessions in the currently running ACP server process, not Hermes' full persisted history (acp.md states sessions are process-local, but acp-internals.md's own 'Current limitations' section contradicts this, stating sessions ARE persisted to the shared ~/.hermes/state.db and transparently restored across restarts, appearing in session_search; the two official docs in the same repo disagree, so the claim as confidently stated is contradicted by a primary source.)
Corrections (authoritative where they conflict with the body)
Claim 2 should be softened: ACP is a standard stdio JSON-RPC protocol, so in principle a Rust ACP client/host could launch hermes acp the same way it would launch any compliant ACP agent binary; however, trogonai's current acp-nats-agent and acp-nats-stdio crates (main branch, commit 058b8bee) contain no subprocess-spawning code and currently operate as a stdio-to-NATS bridge on the agent side, not as a client host that already spawns Claude Code, Gemini CLI, or codex-acp as subprocesses. Do not present the "it already targets" framing as an established fact about trogonai's codebase.
The session-persistence sub-claim in claim 2/3 should be corrected to note a direct conflict between Hermes' own official docs: website/docs/user-guide/features/acp.md says ACP list/load/resume/fork are scoped to the currently running ACP server process (not persisted history), while website/docs/developer-guide/acp-internals.md's "Current limitations" section says ACP sessions ARE persisted to the shared ~/.hermes/state.db and transparently restored across process restarts, appearing in session_search. Treat this as an open discrepancy in Hermes' own documentation rather than a settled fact in either direction until confirmed against the acp_adapter source code itself (acp_adapter/session.py).
