JetBrains, Zed and ACP editors

Run Cusp in any editor that speaks the Agent Client Protocol with `cusp acp` — JetBrains IDEs, Zed, Kiro and others.

cusp acp runs Cusp as an Agent Client Protocol (ACP) agent over standard input and output. Editors that host ACP agents can drive Cusp sessions with it, without a plugin.

Every session the editor starts is an ordinary Cusp session. It shows up in the desktop app and in cusp --resume, and you can continue it from either.

Before you start

  • The cusp CLI is installed. Find its full path with which cusp (macOS, Linux) or where cusp (Windows). Editors start agents without your shell profile, so use the absolute path.
  • A model provider is configured in Cusp (desktop app → Settings → Providers), or a provider key is in the environment, such as ANTHROPIC_API_KEY.
  • Nothing else. cusp acp uses the running daemon (for example the desktop app's) or starts one for the editor.

Set up your editor

AI Assistant in IntelliJ IDEA, WebStorm, PyCharm, GoLand, Rider and the other JetBrains IDEs hosts custom ACP agents from ~/.jetbrains/acp.json.

  1. Open the AI Chat tool window, open the agent menu in its upper-right corner and choose Add Custom Agent. This creates and opens ~/.jetbrains/acp.json.

  2. Add Cusp under agent_servers. The key is the name shown in AI Chat:

    ~/.jetbrains/acp.json
    {
  "default_mcp_settings": {},
  "agent_servers": {
    "Cusp": {
      "command": "/Users/you/.local/bin/cusp",
      "args": ["acp"],
      "env": {}
    }
  }
}

  3. Pick Cusp in the AI Chat agent list and send a prompt.

Notes:

  • Leave default_mcp_settings empty. Cusp uses its own MCP configuration and ignores servers the IDE offers.
  • JetBrains adds the open file, selection and diagnostics automatically only for its built-in agents. With Cusp, attach what you want it to see. Attached files are read through the IDE, so unsaved changes are included.
  • Keys in env are stored in plain text. Prefer configuring providers in Cusp, which keeps keys in the OS keychain.
  • JetBrains doesn't support ACP agents in WSL.

If Cusp doesn't start

Run the command yourself in a terminal:

/full/path/to/cusp acp --verbose

It should wait silently for input, with diagnostics on standard error. If it exits, the message says why. Check the path and the JSON, then restart the editor.

Options

cusp acp [--permission-mode <mode>] [-m <provider:model>] [--effort <level>]
         [--daemon-url <url> --daemon-token <token>] [--data-dir <dir>] [--verbose]
OptionMeaning
--permission-modeDefault permission mode for new sessions
-m, --effortDefault model and reasoning effort for new sessions
--daemon-url, --daemon-tokenConnect to a specific daemon
--data-dirData directory for a daemon cusp acp starts
--verboseLog to standard error. Standard output carries only protocol messages

The editor can still change the mode, model and effort for each session.

What works

In the editorIn Cusp
New, load, resume, list and close sessionsDaemon sessions. Loading replays the conversation; the list is filtered by folder
PromptsText, images, embedded resources and file links. Linked files are read through the editor, so unsaved buffers are seen
StreamingAnswer and thinking text, tool calls with file locations, edit diffs, todo plans, mode, title and context-usage updates
Permission requestsAllow once, Always allow or Deny. Multiple-choice questions are offered as choices
CancelInterrupts the turn and withdraws open approvals
Modes and optionsAsk, Accept edits, Plan, Auto, Don't ask and Bypass, plus model and effort selectors
Slash commands/compact [focus]

Not supported yet

  • MCP servers passed by the editor are ignored. Configure MCP servers in Cusp.
  • Writing files through the editor isn't used. Cusp writes files itself, with checkpoints you can rewind.
  • Running commands in the editor's terminal isn't used. Commands run in Cusp's shell and the output is streamed back.
  • Audio input isn't supported.
  • Authentication methods aren't needed, because Cusp uses the local daemon's configuration.

Next

VS Code

Use Cusp inside VS Code, Cursor or Kiro, with edits reviewed in the diff editor, context from your selection and diagnostics, and native approval prompts.

Agent SDK

Embed the Cusp agent in TypeScript and Python programs, with in-process tools, permission callbacks, hooks, structured output and spending limits.

On this page

Before you startSet up your editorIf Cusp doesn't startOptionsWhat worksNot supported yetNext