zed-hermes-acp

Connect Hermes Agent to Zed via the Agent Client Protocol.

Hermes in Zed via ACP

Wire Hermes Agent into the Zed editor as an ACP External Agent, so you get Hermes's model/provider setup, memory, skills, and tools inside Zed's Agent Panel — without Zed owning your credentials or config. This skill covers the Zed-side wiring (External Agents, the agent_servers config, boundaries, debugging) and the exact Hermes-side ACP launch config. It does NOT cover Zed's native "Zed Agent", Terminal Threads, macOS/Windows paths, or general Zed editing.

Dependency stance: requires Hermes installed with the acp extra (agent-client-protocol), and Zed at/after the ACP External Agents release. All Hermes credentials live in ~/.hermes/ as usual. Hermes-side ACP internals (Buzz bridge, VS Code/JetBrains setup, the full approvals matrix, HERMES_ACP_SKIP_CONFIGURED_MCP) live in the hermes-agent skill — load it for those.

When to Use

• "Add Hermes to Zed" / "use Hermes inside Zed"
• "Configure Zed external agent for Hermes" / "agent_servers hermes"
• "Hermes ACP not showing in Zed" / "Zed can't find hermes acp"
• "ACP external agent Zed config" / wiring any custom ACP agent into Zed

Prerequisites

• Hermes installed and on your PATH (command -v hermes).
• ACP extra installed — invoke through the terminal tool: cd ~/.hermes/hermes-agent && uv pip install -e '.[acp]' This enables hermes acp, hermes-acp, and python -m acp_adapter.
• Hermes provider credentials configured (Zed does NOT supply them): hermes model (interactive), or set in ~/.hermes/.env / ~/.hermes/config.yaml.
• Zed installed. Linux settings path (native install): ~/.config/zed/settings.json.
• Zed as Flatpak (dev.zed.Zed): settings live at ~/.var/app/dev.zed.Zed/config/zed/settings.json, the file is JSONC (// comments + trailing commas), and the sandbox needs the absolute in-sandbox command path ~/.local/bin/hermes (sandbox PATH has no host binaries). No flatpak override is needed — the manifest already grants home + network. Full recipe + JSONC edit workaround in references/zed-flatpak-setup.md. Zed auto-reloads settings (no restart).
• (Optional) ACP browser tools need Node + Chromium via hermes acp --setup-browser (see Pitfalls / hermes-agent skill).

Zed ACP Concepts

Zed supports three agent paths: Zed Agent (Zed-native), External Agents (ACP process you own), and Terminal Threads (raw CLI/TUI). Hermes is an External Agent.

• External Agents run as a separate process, talking to Zed over ACP (stdio JSON-RPC). Zed hosts the thread UI; the agent owns runtime, auth, models, tools.
• Register a custom agent under agent_servers in Zed settings. Zed auto-detects the file change — no restart needed.
• Configuration boundaries (what Zed controls vs Hermes owns):
  • Model/provider config → owned by Hermes
  • Auth / API keys / subscriptions → owned by Hermes
  • Zed Agent profiles → do NOT apply to Hermes
  • Zed Skills → do NOT apply (Hermes uses its own skills)
  • Zed MCP servers → MAY be forwarded to Hermes over ACP
  • Native MCP config → Hermes may also read its own
  • Tool permissions → Zed ACP/tool-forwarding permissions may apply
• See references/zed-external-agents.md (load on demand — skill_view(name='zed-hermes-acp', file_path='references/zed-external-agents.md')) for registry install, common agents, per-agent auth, and thread import.

How to Run

Canonical flow: install the Hermes ACP extra, confirm it launches, then add the hermes-agent entry to Zed's agent_servers and start a thread. Local commands run through the terminal tool. The Zed settings edit uses write_file/patch for native installs, but a tolerant JSONC-aware edit for the Flatpak (see references/zed-flatpak-setup.md) — Hermes's JSON-only writers reject Zed's // comments.

Quick Reference

• Install ACP extra: cd ~/.hermes/hermes-agent && uv pip install -e '.[acp]'
• Launch/check Hermes ACP: hermes acp · hermes acp --version · hermes acp --check
• Health: hermes doctor · hermes status · hermes model
• Optional browser tools: hermes acp --setup-browser (or --yes)
• Zed settings (native): ~/.config/zed/settings.json
• Zed settings (Flatpak): ~/.var/app/dev.zed.Zed/config/zed/settings.json
• Flatpak pre-flight (mimics Zed's spawn): flatpak run --command=bash dev.zed.Zed -c '~/.local/bin/hermes acp --check'
• Zed ACP debug: run dev: open acp logs from the command palette (Ctrl+Shift+P)
• Zed custom-agent config key: agent_servers
• Start thread: Agent Panel → new-thread menu → select hermes-agent

Procedure

1. Install the ACP extra (one time), through the terminal tool:

   bash

   cd ~/.hermes/hermes-agent && uv pip install -e '.[acp]'
   

2. Verify Hermes ACP launches (stdout is reserved for ACP JSON-RPC; logs go to stderr):

   bash

   hermes acp --check
   

   Expect a clean check with no errors. If it errors, run hermes doctor and hermes status.

3. Confirm credentials for the provider you want Hermes to use in Zed:

   bash

   hermes model
   

4. Add Hermes as a custom agent server in Zed. Merge this block under agent_servers (the key is the label shown in Zed's new-thread menu — any name works):

   json

   {
     "agent_servers": {
       "hermes-agent": {
         "type": "custom",
         "command": "~/.local/bin/hermes",
         "args": ["acp"],
         "env": {}
       }
     }
   }
   

   • Native install (~/.config/zed/settings.json): edit with read_file
     • write_file/patch (plain JSON).
   • Flatpak (~/.var/app/dev.zed.Zed/config/zed/settings.json): the file is JSONC — Hermes's write_file/patch tools reject it (strict JSON validation fails on the // comments). Edit with a tolerant method instead (anchor-replace recipe in references/zed-flatpak-setup.md). The command MUST be the absolute in-sandbox path ~/.local/bin/hermes — bare hermes is not on the sandbox PATH. Zed auto-detects the settings change — no restart required.

5. Start a Hermes thread. Open the Agent Panel, use the agent selector / new-thread menu, and pick hermes-agent. Zed connects over ACP; Hermes renders chat, tool activity, file diffs, terminal commands, approval prompts, and streamed thinking.

6. (Optional) Approve tool calls. On first runs Hermes raises permission requests in Zed. Choose:

   • allow_once — this one call only
   • allow_session — all matching calls this ACP session (recommended default)
   • allow_always — writes a permanent Hermes allowlist entry
   • deny — block this call

7. (Optional) Enable browser tools. ACP browser tools need the agent-browser npm package + Chromium, not in the Python wheel:

   bash

   hermes acp --setup-browser --yes
   

   Installs Node 26 into ~/.hermes/node/, npm install -g agent-browser @askjo/camofox-browser, and Playwright Chromium (or uses a detected system Chrome/Chromium). Idempotent.

Pitfalls

• Zed can't find hermes acp → verify command -v hermes and that the ACP extra installed (hermes acp --version). The host command must be hermes with args ["acp"].
• ACP starts then errors → hermes acp --check, hermes doctor, hermes status. Logs are on stderr; stdout must stay clean for JSON-RPC.
• Missing credentials in Zed → Zed does NOT pass its own keys to Hermes. Configure via hermes model or ~/.hermes/.env first.
• Zed Agent profiles / Zed Skills don't apply to Hermes threads — Hermes uses its own profiles, skills, and MCP config. Don't expect Zed's skills or profiles to load.
• Browser tools absent until you run --setup-browser; the ACP toolset includes browser_* only after that bootstrap. Distinct from Hermes's own browser toolset / use_gateway config.
• MCP not appearing → Zed MCP servers may be forwarded over ACP, but Hermes also reads its own native MCP config. Check both. To stop Hermes from auto-starting globally configured MCP servers in ACP, the host can set HERMES_ACP_SKIP_CONFIGURED_MCP=1 (host-set, not user .env).
• ACP debug in Zed → dev: open acp logs from the command palette shows Zed↔agent messages; include when reporting issues.
• Linux settings path — native: ~/.config/zed/settings.json; Flatpak: ~/.var/app/dev.zed.Zed/config/zed/settings.json (unless a custom XDG_CONFIG_HOME). Not the macOS/Windows paths.
• Zed settings.json is JSONC (Flatpak and native) — Hermes's write_file/ patch tools do strict-JSON validation and refuse to write it (the // comments fail the check). Edit with a tolerant method (python anchor-replace; see references/zed-flatpak-setup.md). Never use a JSON-only writer that would strip Zed's comments.
• Flatpak command must be an absolute in-sandbox path (~/.local/bin/hermes), not bare hermes — the sandbox PATH is /app/bin:/usr/bin with no host binaries. No flatpak override is required (manifest already grants home + network).

Verification

Pre-flight the exact spawn Zed will use — works without a display:

bash

flatpak run --command=bash dev.zed.Zed -c '~/.local/bin/hermes acp --check'
# expect: "Hermes ACP check OK"

Then confirm registration and connection in Zed:

1. In Zed, open the command palette (Ctrl+Shift+P) and run dev: open acp logs.
2. Start a hermes-agent thread from the Agent Panel and send a message (e.g. "list files in the current directory").
3. The ACP logs show a successful session/new handshake with Hermes responding. If the thread appears and answers, the integration works.

References (on demand)

Load any with skill_view(name='zed-hermes-acp', file_path='references/<file>'). Linux-focused; macOS/Windows content was dropped during distillation.

• references/zed-flatpak-setup.md — Flatpak path (dev.zed.Zed). Verified recipe: settings at ~/.var/app/dev.zed.Zed/config/zed/settings.json, no flatpak override needed (home+network already granted), command must be absolute in-sandbox ~/.local/bin/hermes, the file is JSONC (Hermes's write_file/patch refuse it — use the python anchor-replace workaround), and the flatpak run --command=bash dev.zed.Zed -c '... acp --check' pre-flight. Load when the user runs Zed as a Flatpak.
• references/zed-external-agents.md — Integration core. ACP registry vs custom-agent install, the agent_servers JSON shape, the Zed↔agent boundary table, per-agent auth, thread import, MCP forwarding, and dev: open acp logs debugging. Load first when wiring or troubleshooting any custom ACP agent in Zed.
• references/zed-agent-paths.md — Contrasts Zed Agent (Zed-owned config) vs Terminal Threads (CLI-owned) vs Hermes-as-External-Agent (ACP, agent-owned via agent_servers), with a decision rule for which path to use. Load when choosing or explaining the agent path.
• references/zed-agent-ui.md — How Hermes (External Agent) appears in the Agent Panel, Agent Settings (External Agents sub-page), and why Agent Profiles do NOT apply; which panel features (checkpoints, history restore, token display, steering, compaction) do/don't apply. Load when configuring or troubleshooting the panel.
• references/zed-tools-permissions.md — Zed's built-in tools, the tool-permission model (precedence, match inputs, Rust-regex rules), and OS sandboxing. Key finding: Zed's sandbox excludes External Agents like Hermes, so Hermes is gated only by tool_permissions, not bwrap. Load when locking down or reasoning about what Hermes can do.
• references/zed-mcp-skills-instructions.md — MCP server install/config, MCP forwarding to External Agents over ACP, the hard line that Zed Skills ≠ Hermes skills (Zed Skills are Zed-Agent-only), and the AGENTS.md instruction model. Load when a Zed MCP tool, Zed Skill, or AGENTS.md isn't reaching Hermes.
• references/zed-ai-features.md — Overview/quick-start/LLM-providers/parallel-agents/inline-assistant distilled into an apply-vs-does-not-apply matrix for Hermes threads. Load when explaining feature coverage.
• references/zed-ai-privacy.md — Data boundary: Hermes (External Agent) owns its provider data, feedback, and training under its own terms; Zed's rating/Edit-Prediction opt-ins apply only to Zed-hosted features. Load when asked whether Zed retains Hermes-thread prompts/code.
• references/zed-cli.md — Zed CLI reference for script/agent integration: opening files/dirs, line:col syntax, window-control flags (-n, -w, -a, -r, --wait, --diff, --user-data-dir, --zed), stdin via zed -, URL handling, default-editor wiring, exit codes. Load when automating Zed from shell/agent scripts.

hermes-agent skill — Hermes-side ACP server internals (Buzz bridge, VS Code/JetBrains setup, the full approvals matrix, HERMES_ACP_SKIP_CONFIGURED_MCP). Load for anything beyond the Zed-side wiring.