ACP Editor Integration

ACP Editor Integration

Hermes Agent can run as an ACP server, letting ACP-compatible editors talk to Hermes over stdio and render:

• chat messages
• tool activity
• file diffs
• terminal commands
• approval prompts
• streamed thinking / response chunks

ACP is a good fit when you want Hermes to behave like an editor-native coding agent instead of a standalone CLI or messaging bot.

What Hermes exposes in ACP mode

Hermes runs with a curated hermes-acp toolset designed for editor workflows. It includes:

• file tools: read_file, write_file, patch, search_files
• terminal tools: terminal, process
• web/browser tools
• memory, todo, session search
• skills
• execute_code and delegate_task
• vision

It intentionally excludes things that do not fit typical editor UX, such as messaging delivery and cronjob management.

Installation

Install Hermes normally, then add the ACP extra:

pip install -e '.[acp]'

This installs the agent-client-protocol dependency and enables:

• hermes acp
• hermes-acp
• python -m acp_adapter

Launching the ACP server

Any of the following 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.

Editor setup

VS Code

Install an ACP client extension, then point it at the repo’s acp_registry/ directory.

Example settings snippet:

{
  "acpClient.agents": [
    {
      "name": "hermes-agent",
      "registryDir": "/path/to/hermes-agent/acp_registry"
    }
  ]
}

Zed

Example settings snippet:

{
  "agent_servers": {
    "hermes-agent": {
      "type": "custom",
      "command": "hermes",
      "args": ["acp"],
    },
  },
}

JetBrains

Use an ACP-compatible plugin and point it at:

/path/to/hermes-agent/acp_registry

Registry manifest

The ACP registry manifest lives at:

acp_registry/agent.json

It advertises a command-based agent whose launch command is:

hermes acp

Configuration and credentials

ACP mode uses the same Hermes configuration as the CLI:

• ~/.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.

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/logging paths, but ACP list/load/resume/fork are scoped to the currently running ACP server process.

Working directory behavior

ACP sessions bind the editor’s 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.

Troubleshooting

ACP agent does not appear in the editor

Check:

• the editor is pointed at the correct acp_registry/ path
• Hermes is installed and on your PATH
• the ACP extra is installed (pip install -e '.[acp]')

ACP starts but immediately errors

Try these checks:

hermes doctor
hermes status
hermes acp

Missing credentials

ACP mode does not have its own login flow. It uses Hermes’ existing provider setup. Configure credentials with:

hermes model

or by editing ~/.hermes/.env.

See also

• ACP Internals
• Provider Runtime Resolution
• Tools Runtime