---
title: Zed and other ACP editors (venom acp)
description: 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.
section: integrations
order: 30
audience: [user, builder, agent]
sources: [packages/acp/AGENTS.md, packages/acp/src/cli.ts, packages/acp/src/ext.ts, packages/acp/src/index.ts, packages/acp/src/agent.ts, docs/adr/0005-acp.md]
features: [integrations.acp]
---

`venom acp` runs venom as an [Agent Client Protocol](https://agentclientprotocol.com) (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 {#zed}

Add venom to Zed's `settings.json`:

```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 {#options}

```bash
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 {#behaviour}

- **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_user` tool 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` (and `sudo` only for a process started with `--mode sudo`) are the session modes and the `mode` config option. An organization policy limits which are offered.
- **Unsaved buffers**: when the editor offers file access, venom's `read`, `edit` and `apply_patch` read 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`, `/context` and `/cost` typed 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/`), so `venom --resume` opens 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 {#ext}

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 {#library}

`@venom/acp` is the library behind `venom acp`, for an app that wants to serve its own harness sessions over ACP:

```ts
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 {#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](/docs/harness/permissions.md): the modes and rules ACP sessions use.
- [The inbox](/docs/automation/inbox.md).
- [Sessions](/docs/cli/sessions.md).
