ghosty-acp

Connect your editor to an ACP agent running on another machine.

Editors launch a command and talk to it over standard input/output. A remote agent lives behind a WebSocket. This swaps the cable — nothing else. No translation, no state, no dependencies.

Not tied to any agent or vendor: if the other end speaks ACP over WebSocket, this works.

Install

Nothing to install — npx fetches it:

npx -y ghosty-acp wss://your-agent.example.com/acp

VS Code

Install the ACP Client extension, then in settings.json:

{
  "acp.agents": {
    "My agent": {
      "command": "npx",
      "args": ["-y", "ghosty-acp", "wss://your-agent.example.com/acp"],
      "env": { "GHOSTY_ACP_TOKEN": "…" }
    }
  }
}

Zed

settings.json:

{
  "agent_servers": {
    "My agent": {
      "type": "custom",
      "command": "npx",
      "args": ["-y", "ghosty-acp", "wss://your-agent.example.com/acp"],
      "env": { "GHOSTY_ACP_TOKEN": "…" }
    }
  }
}

The token is optional — omit it if the other end doesn't require one.

The working directory (cwd)

Your editor runs on your machine; the agent lives in a remote box, and they share no disk. Every ACP client sends the path of the project open on your machine in session/new — a path that does not exist over there. The agent rejects it (Invalid params: invalid directory path) and editors show it as "Failed to connect", which sends you off to check the URL and the token, the two things that were fine.

So the bridge rewrites that one field: cwd becomes /root, or whatever you set in GHOSTY_ACP_CWD. Nothing else in the message is touched.

"env": { "GHOSTY_ACP_TOKEN": "…", "GHOSTY_ACP_CWD": "/workspace" }

The agent edits what is in the box, not your working copy.

⚠️ Put the token in env, never in args

Any process on your machine can read another process's arguments with ps. The token is read from GHOSTY_ACP_TOKEN and appended to the URL inside the process.

Troubleshooting

Diagnostics go to stderr; stdout carries only the JSON-RPC stream, because anything else there breaks the editor.

| Message | Meaning | |---|---| | rechazado (1006) | Bad credential, or the server refused the connection | | la máquina estaba en reposo… | The agent was asleep; connecting wakes it | | conexión cerrada (…) | The other end closed; the bridge exits so the editor notices | | cwd … → … | The project path was remapped to one the agent can see |

Requires Node 22+. MIT.

ghosty-acp — en español

Conecta tu editor a un agente ACP que corre en otra máquina.

Los editores lanzan un comando y le hablan por entrada y salida estándar. Un agente remoto vive detrás de un WebSocket. Esto cambia el cable, y nada más: no traduce, no guarda nada, no tiene dependencias.

No es de ningún agente ni de ningún proveedor en particular: si el otro extremo habla ACP sobre WebSocket, sirve.

Instalación

Nada que instalar — npx lo descarga:

npx -y ghosty-acp wss://tu-agente.example.com/acp

VS Code

Instala la extensión ACP Client y en settings.json:

{
  "acp.agents": {
    "Mi agente": {
      "command": "npx",
      "args": ["-y", "ghosty-acp", "wss://tu-agente.example.com/acp"],
      "env": { "GHOSTY_ACP_TOKEN": "…" }
    }
  }
}

Zed

En settings.json:

{
  "agent_servers": {
    "Mi agente": {
      "type": "custom",
      "command": "npx",
      "args": ["-y", "ghosty-acp", "wss://tu-agente.example.com/acp"],
      "env": { "GHOSTY_ACP_TOKEN": "…" }
    }
  }
}

El token es opcional: si el otro extremo no pide credencial, omítelo.

El directorio de trabajo (cwd)

Tu editor corre en tu máquina y el agente vive en una caja remota: no comparten disco. Todo cliente ACP manda en session/new la ruta del proyecto abierto en tu máquina, una ruta que allá no existe. El agente la rechaza (Invalid params: invalid directory path) y los editores lo pintan como «Failed to connect», que manda a revisar la URL y el token —justo lo que sí estaba bien—.

Por eso el puente reescribe ese único campo: cwd pasa a ser /root, o lo que pongas en GHOSTY_ACP_CWD. Del resto del mensaje no toca nada.

"env": { "GHOSTY_ACP_TOKEN": "…", "GHOSTY_ACP_CWD": "/workspace" }

El agente edita lo que hay en la caja, no tu copia de trabajo.

⚠️ El token va en env, nunca en args

Los argumentos de un proceso los puede leer cualquier otro proceso de la máquina con un ps. Por eso se lee de GHOSTY_ACP_TOKEN y se añade a la URL ya dentro del proceso.

Cuando algo falla

Todo lo que el puente cuenta va a la salida de error; la salida estándar es sólo el flujo JSON-RPC, porque cualquier otra cosa ahí rompe al editor.

| Mensaje | Qué pasa | |---|---| | rechazado (1006) | La credencial no vale, o el servidor no aceptó la conexión | | la máquina estaba en reposo… | El agente estaba dormido; la conexión lo despierta | | conexión cerrada (…) | El otro extremo cerró; el puente sale para que el editor se entere | | cwd … → … | Se remapeó la ruta del proyecto a una que el agente sí ve |

Necesita Node 22 o superior. MIT.

Agent skills inside

The package ships the Ghosty Studio agent skills under skills/ (ghosty-agent, ghosty-acp, ghosty-docs, ghosty-recipe), in the Agent Skills format. Tools that load skills from installed dependencies (e.g. TanStack Intent) pick them up; anyone else can install them with npx skills add https://ghosty.studio or npx skills add blissito/ghosty-skills.