d87a1615ce
- add ACP user and developer docs covering setup, lifecycle, callbacks, permissions, tool rendering, and runtime behavior - add developer guides for agent loop, provider runtime resolution, prompt assembly, context caching/compression, gateway internals, session storage, tools runtime, trajectories, and cron internals - refresh architecture, quickstart, installation, CLI reference, and environments docs to link the new implementation pages and ACP support
198 lines
4.0 KiB
Markdown
198 lines
4.0 KiB
Markdown
---
|
|
sidebar_position: 11
|
|
title: "ACP Editor Integration"
|
|
description: "Use Hermes Agent inside ACP-compatible editors such as VS Code, Zed, and JetBrains"
|
|
---
|
|
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
hermes acp
|
|
```
|
|
|
|
```bash
|
|
hermes-acp
|
|
```
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"acpClient.agents": [
|
|
{
|
|
"name": "hermes-agent",
|
|
"registryDir": "/path/to/hermes-agent/acp_registry"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Zed
|
|
|
|
Example settings snippet:
|
|
|
|
```json
|
|
{
|
|
"acp": {
|
|
"agents": [
|
|
{
|
|
"name": "hermes-agent",
|
|
"registry_dir": "/path/to/hermes-agent/acp_registry"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### JetBrains
|
|
|
|
Use an ACP-compatible plugin and point it at:
|
|
|
|
```text
|
|
/path/to/hermes-agent/acp_registry
|
|
```
|
|
|
|
## Registry manifest
|
|
|
|
The ACP registry manifest lives at:
|
|
|
|
```text
|
|
acp_registry/agent.json
|
|
```
|
|
|
|
It advertises a command-based agent whose launch command is:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
hermes model
|
|
```
|
|
|
|
or by editing `~/.hermes/.env`.
|
|
|
|
## See also
|
|
|
|
- [ACP Internals](../../developer-guide/acp-internals.md)
|
|
- [Provider Runtime Resolution](../../developer-guide/provider-runtime.md)
|
|
- [Tools Runtime](../../developer-guide/tools-runtime.md)
|