# Editors

`bwn acp` speaks the [Agent Client Protocol](https://agentclientprotocol.com/) version 1 on stdin and stdout, so Zed, JetBrains IDEs and Neovim plugins that run ACP agents can drive bwn. The editor shows the streamed reply, each tool call with its diff, the plan, and the approval questions.

## Add it to an editor

In Zed, add this to `settings.json`, then pick buildwithnexus from the Agent Panel's new-thread menu:

```
{
  "agent_servers": {
    "buildwithnexus": {
      "type": "custom",
      "command": "bwn",
      "args": ["acp"],
      "env": {}
    }
  }
}
```

Other ACP clients take the same command and arguments. bwn uses the provider, model and key you set up in the terminal (`~/.buildwithnexus`). Put an API key or `NEXUS_HOME` in `env` to use others. Options from [Headless](https://buildwithnexus.dev/docs/quickstart#headless) go in `args`, for example `["acp", "--permission-mode", "accept-edits"]`. If the editor cannot find `bwn`, give the full path that `command -v bwn` prints.

`bwn acp` takes nothing else on the command line. Anything after it exits 2, because the editor talks to bwn on stdin. One process serves one folder and runs one prompt at a time. Helpers a reply starts run one after another, so the editor can show each one's calls under it. Anything bwn prints besides the protocol goes to stderr, which the editor keeps as the agent's log. A line that is not UTF-8 gets a JSON-RPC parse error, and the server keeps serving.

## Approvals, trust and modes

- **Approvals.** Every approval the terminal would ask for is asked in the editor, with Allow once, Always allow (the terminal's `a`: remembered for this project in your settings) and Reject (told to the model as a denial). Permission modes, allow, ask and deny rules, hooks and the sandbox apply as they do in the terminal. The model's `question` tool gets no answer.
- **Folder trust.** A project's `.buildwithnexus` settings are asked about in the editor at the first prompt, with the same questions. A yes is remembered as in the terminal, and `--trust-project` works too. A project hook whose script changed since you trusted it is skipped, with a warning, as in a headless run.
- **Modes.** Build, Plan and Brainstorm are the session's modes. In Plan the plan arrives as the editor's plan, and building it is a question of its own. Approving it switches the session to Build.
- **Cancel** stops the turn at once, including an open question.

See [Permissions & hooks](https://buildwithnexus.dev/docs/hooks) for what each mode and hook does.

## Files, sessions and MCP

- When the editor offers it, `read_file`, `write_file`, `edit_file` and `multi_edit` read and write through the editor, so they see unsaved buffers and the editor tracks each edit. Commands run in bwn's own shell.
- Each editor thread is a bwn session, saved like any other. The editor can reopen one, and `bwn resume` continues it in the terminal. The file is JSON Lines; the layout is under [Session files](https://buildwithnexus.dev/docs/data#session-files).
- MCP servers the editor passes, over stdio or HTTP, join the ones in your settings. An SSE server is skipped.
- Images and embedded files in a prompt are sent to the model when the model takes images. Audio is not.

MIT licensed · Made by [Garrett Eaglin](https://garretteaglin.com/)
