# ACP — connect your editor

> Connect Zed, VS Code, JetBrains or neovim to a Ghosty Studio agent over the Agent Client Protocol.

URL: https://www.ghosty.studio/en/docs/protocols/acp

Your agent runs in its own machine, with its own disk and terminal. From your editor you talk to it over **ACP** (Agent Client Protocol), the open protocol used by Zed, JetBrains and the VS Code and neovim extensions.

## Why a bridge is needed

Editors don't connect to a web address: they launch a **command** and talk to it over standard input and output. Your agent lives behind a WebSocket. The bridge does that cable swap and nothing else: it carries no secrets and you can read the whole thing, it's sixty lines.

## 1. Nothing to install

The bridge is called `ghosty-acp` and `npx` downloads it on its own, just as Claude Code, Gemini CLI or Copilot do in any editor. You only need Node 22 or newer.

```bash
npx -y ghosty-acp wss://your-agent/acp
```

It has no dependencies and no install scripts. It is published on npm under the MIT license.

## 2. Copy your configuration

In Studio, go to your agent and open **ACP connection**. There you generate the token and we give you the block ready to paste, with your address and token already inside.

**Zed** — `Settings → settings.json`:

```json
{
  "agent_servers": {
    "Ghosty": {
      "type": "custom",
      "command": "npx",
      "args": ["-y", "ghosty-acp", "wss://acp-YOUR-AGENT.../acp"],
      "env": { "GHOSTY_ACP_TOKEN": "gat_…" }
    }
  }
}
```

**VS Code** — install the *ACP Client* extension and paste into `settings.json`:

```json
{
  "acp.agents": {
    "Ghosty": {
      "command": "npx",
      "args": ["-y", "ghosty-acp", "wss://acp-YOUR-AGENT.../acp"],
      "env": { "GHOSTY_ACP_TOKEN": "gat_…" }
    }
  }
}
```

Don't use "Add Agent" from the VS Code sidebar: that wizard only asks for command and arguments, never the key, and the agent ends up without a credential.

**JetBrains and neovim** use the same command + arguments + environment variable trio; check how your client declares ACP agents.

## What you can do from the editor

- Talk to it with the **context of your project**: the agent sees the files you share with it.
- Ask for changes and **review the diff** before applying it, as with any coding agent.
- Use `GHOSTY_ACP_CWD` to set the remote working directory.

## The token

It is your agent's key: whoever has it can talk to it and use its terminal. It goes in the **environment variable** of the configuration, never in the command arguments: any program on your machine can read another's arguments. If you think it leaked, **rotate it** from the panel: the old one dies instantly.

## When something doesn't work

| Symptom | Cause |
|---|---|
| "rejected (1006)" | The token doesn't match. If you rotated it, copy the block again. |
| Takes a few seconds to start | Normal: the machine sleeps and the first connection wakes it. |
| "already serving N conversations" | Each open session takes a slot. Close one and come back. |
| The editor stays silent | The bridge writes to standard error. In Zed: *agent panel → View logs*. |