ACP Editor Integration for Hermes Agent: Run AI Coding in Your IDE
Run Hermes Agent as an ACP server inside VS Code, Zed, or JetBrains.
This page documents the ACP (Agent Client Protocol) editor integration for Hermes Agent, which allows you to run Hermes as a coding agent directly inside your IDE. Once wired up, the agent can read and write files, execute terminal commands, browse the web, and respond to approval prompts, all within the editor's native interface.
What It Does
The ACP integration enables Hermes Agent to communicate with ACP-compatible editors over standard I/O (stdio), rendering the following in-editor:
- Chat messages
- Tool activity
- File diffs
- Terminal commands
- Approval prompts
- Streamed thinking and response chunks
ACP is designed for editor-native coding agent workflows rather than standalone CLI or messaging bot interactions. According to the official documentation, it is "a good fit when you want Hermes to behave like an editor-native coding agent instead of a standalone CLI or messaging bot."
In ACP mode, Hermes runs with a curated toolset called hermes-acp that is tailored for editor workflows. The included tools are:
- File tools:
read_file,write_file,patch,search_files - Terminal tools:
terminal,process - Web and browser tools
- Memory, todo, session search
- Skills
execute_codeanddelegate_task- Vision
The toolset intentionally excludes features that do not fit typical editor UX, such as messaging delivery and cronjob management.
Setup
Installation
Install Hermes normally, then add the ACP extra from the install checkout. The official documentation provides the following command:
cd ~/.hermes/hermes-agent && uv pip install -e '.[acp]'
This installs the agent-client-protocol dependency and enables the following entry points:
hermes acphermes-acppython -m acp_adapter
Launching the ACP Server
Any of the following commands starts Hermes in ACP mode:
hermes acp
hermes-acp
python -m acp_adapter
Hermes logs to stderr so stdout remains reserved for ACP JSON-RPC traffic.
For non-interactive checks, use:
hermes acp --version
hermes acp --check
Browser Tools (Optional)
Browser tools such as browser_navigate, browser_click, and others depend on the agent-browser npm package and Chromium, which are not part of the Python wheel. Install them with:
hermes acp --setup-browser # interactive (prompts before ~400 MB download)
hermes acp --setup-browser --yes # accept the download non-interactively
This is the standalone command. The terminal-auth flow (hermes acp --setup) also offers the browser bootstrap as a follow-up question after model selection, so most users never need to run --setup-browser directly.
What the browser setup does:
- Installs Node.js 22 LTS into
~/.hermes/node/if missing - Runs
npm install -g agent-browser @askjo/camofox-browserinto that prefix (no sudo needed because npm's--prefixpoints at the user-writable Hermes-managed Node) - Installs Playwright Chromium, or uses a detected system Chrome or Chromium when available
The bootstrap is idempotent. Re-running it is fast and skips work that is already done.
Editor Setup
VS Code
Install the ACP Client extension from the VS Code marketplace.
To connect:
- Open the ACP Client panel from the Activity Bar.
- Select Hermes Agent from the built-in agent list.
- Connect and start chatting.
If you want to define Hermes manually, add it through VS Code settings under acp.agents:
{
"acp.agents": {
"Hermes Agent": {
"command": "hermes",
"args": ["acp"]
}
}
}
Zed
Configure Hermes as a custom agent server in Zed settings:
- Open the Agent Panel.
- Add a custom agent server with the following configuration:
{
"agent_servers": {
"hermes-agent": {
"type": "custom",
"command": "hermes",
"args": ["acp"]
}
}
}
- Start a new Hermes external-agent thread.
Prerequisites: Configure Hermes provider credentials first with hermes model, or set them in ~/.hermes/.env or ~/.hermes/config.yaml.
JetBrains
Use an ACP-compatible plugin and point it at hermes acp or hermes-acp. The official documentation does not specify a particular plugin name.
Configuration Reference
ACP mode uses the same Hermes configuration as the CLI. The following files and directories are used:
~/.hermes/.env~/.hermes/config.yaml~/.hermes/skills/~/.hermes/state.db
Provider resolution uses Hermes' normal runtime resolver, so ACP inherits the currently configured provider and credentials. Hermes also advertises a terminal auth method (--setup) for first-run ACP clients; this opens Hermes' interactive model and provider setup.
Host Integration Variables
The following environment variable is set by an ACP host process (an editor or another agent harness) on the Hermes subprocess it spawns. These are not user configuration and should not be set by hand in .env or config.yaml.
| Variable | Value | Effect |
|---|---|---|
HERMES_ACP_SKIP_CONFIGURED_MCP | 1 | Skip starting the globally configured MCP servers from config.yaml before the ACP JSON-RPC loop begins. |
Hermes normally starts every MCP server configured in config.yaml before it enters the ACP JSON-RPC loop. A host that owns MCP itself, passing the session's servers explicitly through session/new, does not need that global startup. An unrelated slow or interactive MCP server would otherwise delay initialize. Setting the marker to exactly 1 lets such a host skip it.
Only the global config.yaml discovery is skipped. MCP servers supplied by the ACP session through session/new are still registered, so a host loses no capability it asked for. Any other value (unset, empty, 0, false) keeps the default behavior, so an unrelated truthy-looking string cannot silently disable MCP.
How It Works
Session Behavior
ACP sessions are tracked by the ACP adapter's in-memory session manager while the server is running. Each session stores:
- Session ID
- Working directory
- Selected model
- Current conversation history
- Cancel event
The underlying AIAgent still uses Hermes' normal persistence and logging paths, but ACP operations like list, load, resume, and fork are scoped to the currently running ACP server process.
Working Directory Behavior
ACP sessions bind the editor's current working directory (cwd) to the Hermes task ID so file and terminal tools run relative to the editor workspace, not the server process cwd.
Approvals
Dangerous terminal commands can be routed back to the editor as approval prompts. ACP approval options are simpler than the CLI flow:
- Allow once
- Allow always
- Deny
On timeout or error, the approval bridge denies the request.
Session-Scoped Edit Auto-Approval
ACP exposes a third tier between "allow once" and "allow always": "Allow for session." Picking it from the editor's permission prompt records the approval inside the current ACP session only. Every subsequent matching command in that session goes through without prompting, but a new ACP session (or restarting the editor) resets the slate and re-prompts the first time.
| Option | Editor label | Scope | Persisted across restarts |
|---|---|---|---|
allow_once | Allow once | This one tool call | No |
allow_session | Allow for session | All matching calls in this ACP session | No, cleared when the session ends |
allow_always | Allow always | All future sessions | Yes, written to the Hermes permanent allowlist |
deny | Deny | This one tool call | No |
allow_session is the right default for an editor workflow where you trust an agent for the duration of a task but do not want to grant a long-lived allowlist entry. The safety trade-off is straightforward: the broader the scope, the less the editor will interrupt you, and the more damage a misbehaving agent (or prompt injection) can do before you notice. Start with allow_once for unfamiliar commands; promote to allow_session once you have seen the agent run the same pattern correctly a few times; reserve allow_always for truly idempotent commands you trust forever (for example, git status).
The ACP bridge maps these options onto Hermes' internal approval semantics. allow_always writes a permanent allowlist entry the same way the CLI does, while allow_session only affects the in-process approval cache for the current ACP session.
Requirements and Limitations
- Hermes must be installed and on your PATH.
- The ACP extra must be installed via
cd ~/.hermes/hermes-agent && uv pip install -e '.[acp]'. - Provider credentials must be configured before use, either with
hermes modelor by editing~/.hermes/.env. - Browser tools require Node.js 22 LTS and the
agent-browsernpm package, which are installed via the--setup-browserflag. This involves an approximately 400 MB download. - ACP sessions are in-memory only; session history is not persisted across server restarts.
- The
HERMES_ACP_SKIP_CONFIGURED_MCPvariable is intended for host processes only and should not be set manually by users. - The toolset intentionally excludes messaging delivery and cronjob management.
Troubleshooting
ACP agent does not appear in the editor
Check the following:
- For manual or local development, verify the custom
agent_serverscommand points tohermes acp. - Hermes is installed and on your PATH.
- The ACP extra is installed:
cd ~/.hermes/hermes-agent && uv pip install -e '.[acp]'.
ACP starts but immediately errors
Try these diagnostic commands:
hermes acp --version
hermes acp --check
hermes doctor
hermes status
Missing credentials
ACP mode uses Hermes' existing provider setup. Configure credentials with:
hermes model
or by editing ~/.hermes/.env. The terminal auth flow (hermes acp --setup) can also trigger the interactive provider and model setup.
Sources & References
This page was researched from 1 independent source, combined and verified for completeness.
- 1.ACP Editor IntegrationOfficial documentation · primary source
The #1 AI Newsletter
The most important ai updates, guides, and fixes — one weekly email.
No spam, unsubscribe anytime. Privacy policy