Channels and Plugins

This page is for people using channel plugins in Cola. If you want to build your own plugin, see Plugin SDK.

Channels vs. Plugins

A channel is the connection you see in Cola, such as WeChat, Feishu, a device, or a bot account. A plugin is the local code package that backs it. A single plugin can implement a channel, register LLM-callable tools that work in every session (no channel required), or quietly observe activity across all your sessions — or any combination of the three. This page focuses on installing and managing them; for what a plugin can actually do, see Plugin SDK.

Cola discovers installed plugins from ~/.cola/plugins/<id>/package.json. A plugin directory can come from any repository; it does not need to live in the official Cola plugins repository. The directory root only needs a valid package.json, and cola.plugin.entry must point to a built JavaScript file.

Install only plugins you trust. Plugins run locally inside the Cola server process and may connect to external messaging platforms or expose tools to every session.

Install a Local Plugin

Local plugin install expects the plugin directory root, not the dist/ directory.

A valid directory usually looks like this:

stackchan/
  package.json
  dist/
    index.js
  node_modules/

The package.json declares the plugin identity and entry point:

{
  "cola": {
    "plugin": {
      "id": "stackchan",
      "entry": "./dist/index.js"
    }
  }
}

dist/ is only the build output directory. It is not enough by itself. If you select stackchan/dist/, Cola cannot read the root package.json or cola.plugin metadata, so it cannot install the plugin.

If the plugin does not bundle its dependencies into dist/, the plugin directory also needs runtime dependencies such as node_modules/. Cola does not run npm install when installing a local directory.

Manage from the UI

1. Open Cola.
2. Open the Connections tab in settings.
3. Click Install Local Plugin. The first time, Cola shows a short guide pointing at the Plugin SDK docs so the plugin's manifest and entry file are ready before you pick the folder. You can dismiss the guide and continue, or open the docs and come back.
4. Select the plugin directory root, such as stackchan/.
5. After installation, the plugin appears in the connections list.

Each row in the list is a card. Clicking the title or hint opens the plugin's README when one is provided. Available row actions depend on the channel:

• Configure: enter tokens, server addresses, or other channel settings.
• Connect: start QR-code login, OAuth, or another login flow.
• Disconnect: sign out of the current channel account.
• More: behind the overflow menu — open the plugin docs, or uninstall the plugin.

Built-in channels do not show the uninstall action. WeChat is built into Cola and cannot be removed or overwritten through local plugin install.

The list refreshes its cloud catalogue automatically each time you open the tab. If the catalogue cannot be loaded, the list falls back to showing only the channels you already have installed.

Manage from the CLI

The CLI separates plugin lifecycle from channel connection state:

• cola plugin ... installs, lists, enables, disables, and uninstalls plugins.
• cola channel ... checks connection status, logs in, and logs out.

Install a local plugin directory:

cola plugin install /path/to/stackchan

List installed plugins:

cola plugin list

Uninstall a local plugin:

cola plugin uninstall stackchan

Enable or disable a plugin:

cola plugin enable stackchan
cola plugin disable stackchan

Check channel status:

cola channel status

Log in or log out of a channel:

cola channel login stackchan
cola channel logout stackchan

If Cola is running, install and uninstall try to refresh the active plugin list. If Cola is not running, the change applies the next time Cola starts.

Troubleshooting

Why can't I install dist/?

dist/ only contains the runtime entry. Cola needs the root package.json to read the plugin ID, label, entry file, and channel metadata.

The plugin installed but does not appear

Check that cola.plugin.entry points to an existing file, such as dist/index.js. If it does not exist, run the plugin's own build command first.

The plugin fails with a missing dependency

Bundle runtime dependencies into dist/, or keep a working node_modules/ directory inside the plugin directory.

Why can't I uninstall WeChat?

WeChat is a built-in channel. Built-in channels are managed by the Cola app and are not removed as user-installed local plugins.