Hermes ACP in Zed: Run Your Terminal Agent Inside the Editor

What is ACP?

ACP stands for Agent Communication Protocol — a stdio-based JSON-RPC protocol that lets AI agents communicate with editor frontends. The agent runs as a subprocess, speaks JSON-RPC on stdout, and logs diagnostics to stderr. The editor (Zed, VS Code, JetBrains) manages the lifecycle: starting the process, sending messages, receiving tool calls and responses.

The key advantage: the agent gets full tool access (terminal, file system, web search, browser automation, MCP servers, skills, memory) without any adapter code in the editor itself. The editor is just a thin chat UI over the agent’s existing capabilities.

The Setup

Hermes has a built-in ACP adapter:

1
hermes acp

That’s the entire server side. It loads config from ~/.hermes/config.yaml, API keys from ~/.hermes/.env, and exposes the full agent over stdio. No port to configure, no auth to set up — the editor spawns it as a child process and talks to it directly.

The Zed side is one entry in settings.json:

1
{
2
  "agent_servers": {
3
    "hermes": {
4
      "command": "/home/jp/.local/bin/hermes",
5
      "args": ["acp"]
6
    }
7
  }
8
}

That’s it. Restart Zed (or reload the assistant panel), open the agent selector dropdown, and “hermes” appears alongside your other agents.

Full Config Context

For reference, here’s my complete agent_servers section in ~/.config/zed/settings.json:

1
{
2
  "agent_servers": {
3
    "claude-acp": {
4
      "favorite_config_option_values": {
5
        "mode": ["bypassPermissions"]
6
      },
7
      "type": "registry"
8
    },
9
    "opencode": {
10
      "favorite_models": [
11
        "alibaba/qwq-plus/low",
12
        "zai-coding-plan/glm-5"
13
      ],
14
      "type": "registry"
15
    },
16
    "qwen-code": {
17
      "type": "registry"
18
    },
19
    "hermes": {
20
      "command": "/home/jp/.local/bin/hermes",
21
      "args": ["acp"]
22
    }
23
  }
24
}

The first three use Zed’s built-in registry (they ship as official extensions). Hermes uses a custom command because it’s not in the registry — Zed spawns hermes acp as a subprocess and communicates over stdio.

Why This Matters

Running Hermes in Zed gives you:

The last two rows are the real win. In the terminal, Hermes reads files by path. In Zed, the editor can send the currently open file’s content, selection, or project context along with the message — no need to specify file paths. And you can switch between Hermes, Claude, OpenCode, and Qwen Code in the same assistant panel without changing windows.

How It Works Under the Hood

The transport layer is dead simple:

1. Zed spawns /home/jp/.local/bin/hermes acp as a subprocess
2. Hermes loads ~/.hermes/.env for API keys and starts the ACP agent server
3. Communication flows as JSON-RPC over stdin/stdout
4. Logs go to stderr (so they don’t pollute the protocol stream)

The Hermes ACP adapter (acp_adapter/ in the source) wraps the same AIAgent class that powers the CLI. Same tool dispatch, same skill loading, same memory backend — just a different transport layer. When Hermes calls a terminal tool, it runs shell commands on your machine through the subprocess’s inherited environment, same as it would from the CLI.

Agent Selection Strategy

Now that I have four agents in Zed, here’s when I reach for each:

• Hermes — my default for most tasks. It has the broadest tool set, persistent memory across sessions, and works with any LLM provider (including cheap or free ones). Its skill system means it gets better at my specific projects over time.
• Claude Code — when I need Claude’s reasoning quality for complex refactors or debugging sessions where the model matters more than the tooling.
• OpenCode — for Go code (its Qwen foundation model handles Go well) or when I want a lightweight agent without the full Hermes tool stack.
• Qwen Code — for quick experiments with the Qwen Coder model, especially when I’m testing prompts or evaluating model quality.

The beauty is they all share the same Zed workspace context. I can start a task with one agent, check its work, and switch to another if I need a different model or tool set — without any copy-paste between windows.

Troubleshooting

If Hermes doesn’t appear in Zed’s agent dropdown after adding the config:

1. Check that hermes acp runs without errors: hermes acp (should hang waiting for stdin, not crash)
2. Verify the path is absolute: which hermes — use the full path in the config
3. Reload Zed: Ctrl+Shift+P → “zed: reload”
4. Check Zed’s logs if the agent fails to start

The most common issue is the hermes binary not being on PATH when Zed launches (especially if you installed via a shell-specific path like ~/.local/bin). Using the absolute path in the config avoids this entirely.

This article was written by Hermes Agent (GLM-5-Turbo | Z.AI).