hermes-agent/website/docs/developer-guide/programmatic-integration.md

sidebar_position	title	description
8	Programmatic Integration	Three protocols for driving hermes-agent from external programs: ACP, the TUI gateway JSON-RPC, and the OpenAI-compatible HTTP API

Programmatic Integration

Hermes ships three protocols for driving the agent from external programs — IDE plugins, custom UIs, CI pipelines, embedded sub-agents. Pick the one that matches your transport and consumer.

Protocol	Transport	Best for	Defined by
ACP	JSON-RPC over stdio	IDE clients (VS Code, Zed, JetBrains) that already speak the Agent Client Protocol	acp_adapter/
TUI gateway	JSON-RPC over stdio (or WebSocket)	Custom hosts that want fine-grained control of sessions, slash commands, approvals, and streaming events	tui_gateway/server.py
API server	HTTP + Server-Sent Events	OpenAI-compatible frontends (Open WebUI, LobeChat, LibreChat…) and language-agnostic web clients	gateway/platforms/api_server.py

All three drive the same AIAgent core. They differ only in wire format and which set of features they expose.

---

ACP (Agent Client Protocol)

hermes acp starts a stdio JSON-RPC server speaking ACP. Used in production by VS Code (Zed Industries' ACP extension), Zed, and any JetBrains IDE with an ACP plugin.

Capabilities exposed: session creation, prompt submission, streaming agent message chunks, tool-call events, permission requests, session fork, cancel, and authentication. Tool output is rendered into ACP Diff/ToolCall content blocks the IDE understands.

Full lifecycle, event bridge, and approval flow: ACP Internals.

hermes acp                  # serve ACP on stdio
hermes acp --bootstrap      # print install snippet for an ACP-capable IDE

---

TUI Gateway JSON-RPC

tui_gateway/server.py is the protocol the Ink TUI (hermes --tui) and the embedded dashboard PTY bridge talk to. Any external host can speak the same protocol over stdio (or WebSocket via tui_gateway/ws.py).

Method catalog (selected)

prompt.submit           prompt.background       session.steer
session.create          session.list            session.interrupt
session.history         session.compress        session.branch
session.title           session.usage           session.status
clarify.respond         sudo.respond            secret.respond
approval.respond        config.set / config.get commands.catalog
command.resolve         command.dispatch        cli.exec
reload.mcp              reload.env              process.stop
delegation.status       subagent.interrupt      spawn_tree.save / list / load
terminal.resize         clipboard.paste         image.attach

Events streamed back

message.delta, message.complete, tool.start, tool.progress, tool.complete, approval.request, clarify.request, sudo.request, secret.request, gateway.ready, plus session lifecycle and error events.

Pi-style RPC mapping

Every command in the Pi-mono RPC spec (issue #360) has a TUI-gateway equivalent:

Pi command	Hermes equivalent
prompt	prompt.submit (or ACP session/prompt)
steer	session.steer
follow_up	prompt.submit queued after current turn
abort	session.interrupt
set_model	command.dispatch for /model <provider:model> (mid-session, persistent)
compact	session.compress
get_state	session.status
get_messages	session.history
switch_session	session.resume
fork	session.branch
ui_request / ui_response	clarify.respond / sudo.respond / secret.respond / approval.respond

---

OpenAI-Compatible API Server

gateway/platforms/api_server.py exposes hermes over HTTP for any client that already speaks the OpenAI format. Useful when you want a web frontend, a curl-driven CI runner, or a non-Python consumer.

Endpoints:

POST /v1/chat/completions        OpenAI Chat Completions (streaming via SSE)
POST /v1/responses               OpenAI Responses API (stateful)
POST /v1/runs                    Start a run, returns run_id (202)
GET  /v1/runs/{id}               Run status
GET  /v1/runs/{id}/events        SSE stream of lifecycle events
POST /v1/runs/{id}/approval      Resolve a pending approval
POST /v1/runs/{id}/stop          Interrupt the run
GET  /v1/capabilities            Machine-readable feature flags
GET  /v1/models                  Lists hermes-agent
GET  /health, /health/detailed

Setup, headers (X-Hermes-Session-Id, X-Hermes-Session-Key), and frontend wiring: API Server.

---

Which one should I use?

• You're writing an IDE plugin and the IDE already speaks ACP → ACP. Zero protocol work on the IDE side.
• You're writing a custom desktop / web / TUI host and want every Hermes feature (slash commands, approvals, clarify, multi-agent, session branching) → TUI gateway JSON-RPC.
• You want any OpenAI-compatible frontend, a language-agnostic HTTP client, or curl-driven automation → API server.
• You want a Python in-process embed without a subprocess → import run_agent.AIAgent directly. See Agent Loop.

---

Model hot-swapping

Mid-session model switching works on every surface — it's the /model slash command under the hood.

• CLI / TUI: /model claude-sonnet-4 or /model openrouter:anthropic/claude-sonnet-4.6
• TUI gateway RPC: command.dispatch with {"command": "/model claude-sonnet-4"}
• ACP: the IDE sends the slash command as a prompt; the agent dispatches it
• API server: include a model field in the request body or set X-Hermes-Model

Provider-aware resolution (the same model name picks the right format for whatever provider you're on) is built in. See hermes_cli/model_switch.py.

---

A note on --mode rpc

Hermes does not have a --mode rpc flag. The three protocols above already cover the use cases — ACP for IDE-protocol clients, the TUI gateway for stdio JSON-RPC hosts, and the API server for HTTP. If you find a real gap that none of them fill, open an issue with the concrete consumer you're building.