Zed and other ACP editors (venom acp)
Use venom as the agent inside Zed or any editor that speaks the Agent Client Protocol, with venom acp on stdio, venom's permission modes, saved sessions shared with the terminal, and the _venom inbox and fleet extension methods.
venom acp runs venom as an Agent Client Protocol (ACP) agent. The editor starts the process and speaks JSON-RPC over its stdin and stdout; you don't run it by hand. Each ACP session is a full venom harness session (permission engine, sandbox, hooks, memory, MCP, subagents, plan and todo) in the directory the editor sends. Protocol version 1.
Set up Zed
Add venom to Zed's settings.json:
{
"agent_servers": {
"Venom": { "type": "custom", "command": "venom", "args": ["acp"], "env": {} }
}
}Then pick Venom in Zed's agent panel. Put flags in args (["acp", "--mode", "accept-edits"]) and anything venom needs to reach a model in env (VENOM_BASE_URL, VENOM_API_KEY), unless Zed's own environment already has them. Other ACP editors take the same command and arguments.
Options
venom acp --help
venom acp --mode accept-edits --model venom-smart| Option | What it does | Default |
|---|---|---|
--mode <mode> |
The initial permission mode: plan, default, accept-edits, auto, yolo, or sudo (no prompts, no OS sandbox; shown in the editor but never switched into from it). The editor can switch the mode per session. |
your config, else default |
--model <id> |
The model for new sessions. | VENOM_MODEL, else venom-default |
--approve, -a |
Trust each session's project: its hooks, MCP servers and allow rules. Without it, a project is trusted only if you trusted it earlier in the TUI. | off |
--max-sessions <n> |
Sessions the editor may hold open at once. Past it, session/new, session/load and session/resume fail with JSON-RPC error -32029 until one is closed. |
64 |
-h, --help |
Print the help. |
Environment: VENOM_BASE_URL, VENOM_API_KEY, VENOM_MODEL, VENOM_ALIAS_MAP and the rest, as for venom. VENOM_SEARCH_URL adds web_search; VENOM_OFFLINE=1 makes sessions offline.
What the editor gets
- Tool calls stream with a kind, a title with workspace-relative paths, file locations, and status pending, in progress, completed or failed. Edits and writes come as diffs; bash output streams as text.
- Permissions: when venom's policy asks, the editor shows a permission request with allow once, always allow (the request's rules, for this session) and reject. A subagent's call appears as its own tool call titled
[agent]. A rejection reaches the model as "The user rejected this tool call in the editor." - Questions from the agent's
ask_usertool appear as permission requests whose options are the answers, plus "None of these: decide yourself". - Plans: venom's todo list is sent as the ACP plan.
- Modes:
plan,default,accept-edits,auto,yolo(andsudoonly for a process started with--mode sudo) are the session modes and themodeconfig option. An organization policy limits which are offered. - Unsaved buffers: when the editor offers file access, venom's
read,editandapply_patchread text through the editor, so the agent sees unsaved changes, and writes go to disk and then to the editor. Bash, grep, find and ls read the disk. - Prompts may carry text,
@file links, embedded selections and images./undo,/redo,/checkpoints,/contextand/costtyped as a prompt run locally with no model request. - Cancel stops the run and the running command; subagents return partial reports. A second cancel within 1 s stops the whole agent tree.
- Saved sessions are venom's own saved sessions (
~/.venom/agent/sessions/), sovenom --resumeopens an editor session and the editor can list and load a terminal one. Loading a session saved for another directory is refused.
Not supported: ACP terminals (bash runs inside venom's sandbox), MCP servers sent by the editor (venom loads .mcp.json and its own config), audio prompts, a model selector, session/fork and session/delete.
Extension methods
ACP reserves names starting with an underscore for extensions. venom adds three, listed in agentCapabilities._meta.venom.methods. They expose the host-wide inbox of human decisions, the same queue as venom inbox and GET /v1/inbox. They only collect answers; venom's decision tools never decide on their own.
| Method | Params | Result |
|---|---|---|
_venom/inbox |
none | {items}: the open inbox items, most urgent first, each with its rank. |
_venom/inbox/resolve |
{id, action, message?}: action is an inbox action (approve, reject, redirect, take-over); redirect needs a message (at most 10,000 characters). |
{id, action, message?}. Invalid params for an unknown or already answered item, a bad action, or redirect without a message. |
_venom/fleet |
none | {sessions: [{sessionId, cwd, title?, updatedAt, open, inbox}], inbox}: every saved session on this host, whether it is open in this connection, and its open inbox items. |
Embedding: @venom/acp
@venom/acp is the library behind venom acp, for an app that wants to serve its own harness sessions over ACP:
import { ndJsonStream } from "@agentclientprotocol/sdk";
import { serveAcp } from "@venom/acp";
serveAcp(ndJsonStream(output, input), { harness: { provider: { baseUrl, apiKey } } });It also exports runAcp and parseAcpArgs (the CLI), DEFAULT_MAX_SESSIONS and TOO_MANY_SESSIONS, AcpSession, the mode helpers and the tool-call mapping. The package ships a standalone venom-acp binary.
Errors
| Error | Meaning |
|---|---|
-32029 Too many sessions |
--max-sessions sessions are open. Close one with session/close, or raise the limit. |
-32602 invalid params on session/load |
The session belongs to another directory (data.sessionCwd names it), or the mode isn't allowed. |
| -32603 on a prompt | The model call failed; the message says why. |
| -32700, -32600, -32601 | Bad JSON, a non-message or a batch, an unknown method. They are answered, never fatal. |
Related
- Permissions: the modes and rules ACP sessions use.
- The inbox.
- Sessions.