Skip to main content

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:

{
  "acp": {
    "agents": [
      {
        "name": "hermes-agent",
        "registry_dir": "/path/to/hermes-agent/acp_registry"
      }
    ]
  }
}

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​