Skip to main content

ACP Editor Integration

KOPI O Agent can run as an ACP server, letting ACP-compatible editors talk to Kopi over stdio and render:

  • chat messages
  • tool activity
  • file diffs
  • terminal commands
  • approval prompts
  • streamed thinking / response chunks

ACP is a good fit when you want Kopi to behave like an editor-native coding agent instead of a standalone CLI or messaging bot.

What Kopi exposes in ACP mode​

Kopi runs with a curated kopi-acp toolset designed for editor workflows. It includes:

  • file tools: read_file, write_file, patch, search_files
  • terminal tools: terminal, process
  • web/browser tools
  • memory, todo, session search
  • skills
  • execute_code and delegate_task
  • vision

It intentionally excludes things that do not fit typical editor UX, such as messaging delivery and cronjob management.

Installation​

Install Kopi normally, then add the ACP extra:

pip install -e '.[acp]'

This installs the agent-client-protocol dependency and enables:

  • kopi acp
  • kopi-acp
  • python -m acp_adapter

Launching the ACP server​

Any of the following starts Kopi in ACP mode:

kopi acp
kopi-acp
python -m acp_adapter

Kopi logs to stderr so stdout remains reserved for ACP JSON-RPC traffic.

Editor setup​

VS Code​

Install the ACP Client extension.

To connect:

  1. Open the ACP Client panel from the Activity Bar.
  2. Select KOPI O Agent from the built-in agent list.
  3. Connect and start chatting.

If you want to define Kopi manually, add it through VS Code settings under acp.agents:

{
  "acp.agents": {
    "KOPI O Agent": {
      "command": "kopi",
      "args": ["acp"]
    }
  }
}

Zed​

Example settings snippet:

{
  "agent_servers": {
    "kopi-agent": {
      "type": "custom",
      "command": "kopi",
      "args": ["acp"],
    },
  },
}

JetBrains​

Use an ACP-compatible plugin and point it at:

/path/to/kopi-agent/acp_registry

Registry manifest​

The ACP registry manifest lives at:

acp_registry/agent.json

It advertises a command-based agent whose launch command is:

kopi acp

Configuration and credentials​

ACP mode uses the same Kopi configuration as the CLI:

  • ~/.kopi/.env
  • ~/.kopi/config.yaml
  • ~/.kopi/skills/
  • ~/.kopi/state.db

Provider resolution uses Kopi' normal runtime resolver, so ACP inherits the currently configured provider and credentials.

Session behavior​

ACP sessions are tracked by the ACP adapter's in-memory session manager while the server is running.

Each session stores:

  • session ID
  • working directory
  • selected model
  • current conversation history
  • cancel event

The underlying AIAgent still uses Kopi' normal persistence/logging paths, but ACP list/load/resume/fork are scoped to the currently running ACP server process.

Working directory behavior​

ACP sessions bind the editor's cwd to the Kopi task ID so file and terminal tools run relative to the editor workspace, not the server process cwd.

Approvals​

Dangerous terminal commands can be routed back to the editor as approval prompts. ACP approval options are simpler than the CLI flow:

  • allow once
  • allow always
  • deny

On timeout or error, the approval bridge denies the request.

Troubleshooting​

ACP agent does not appear in the editor​

Check:

  • the editor is pointed at the correct acp_registry/ path
  • Kopi is installed and on your PATH
  • the ACP extra is installed (pip install -e '.[acp]')

ACP starts but immediately errors​

Try these checks:

kopi doctor
kopi status
kopi acp

Missing credentials​

ACP mode does not have its own login flow. It uses Kopi' existing provider setup. Configure credentials with:

kopi model

or by editing ~/.kopi/.env.

See also​