OpenCode Chat Bridge

Bridge ACP-compatible agents such as OpenCode and Ferrum to chat platforms with permission-based security.

Recent Changes

• Global tool presentation modes: off, events, status, and trace. Editable status and cumulative audit messages work across every chat connector, with progressive ACP argument updates, pagination, and edit-failure recovery.
• Telegram connector accepts file attachments from users (photo, document, video, audio, voice, animation, video note, sticker). Attachments are downloaded to the session workspace and exposed to the LLM as local file paths.
• ACP backend executable, arguments, identity, and workspace profile are configurable
• ACP sessions persist across bridge restarts and remain isolated per chat thread
• New cross-connector allowedUsers allowlists for Slack, WhatsApp, Matrix, Discord, Mattermost, and Telegram
• New Telegram connector with per-topic sessions in forum supergroups
• Breaking change: WhatsApp renamed allowedNumbers to allowedUsers and WHATSAPP_ALLOWED_NUMBERS to WHATSAPP_ALLOWED_USERS
• Slack, Mattermost, Matrix, and Telegram support per-thread session isolation

Table of Contents

• Connectors -- Matrix, Slack, WhatsApp, Mattermost, Discord, Telegram, Web
• Deployment Model
• Quick Start
• Usage
• ACP Backends
• Permissions
• MCP Servers
• AGENTS.md
• Security
• Project Structure
• Library Usage
• Requirements
• Documentation

Connectors

Matrix

Supports E2EE (encrypted rooms), image uploads, and integrates with Element and other Matrix clients. Uses native Rust crypto with persistent key storage.

Slack

Uses Socket Mode for real-time messaging without requiring a public server. Each thread gets its own isolated session -- reply naturally without re-mentioning the bot.

WhatsApp

Uses Baileys for WebSocket-based communication. Scan a QR code once to link.

Mattermost

Uses the Mattermost REST API v4 and WebSocket for real-time events. Zero external dependencies -- uses native fetch and WebSocket. Works with any Mattermost instance (self-hosted or cloud). Supports @mentions, DMs, file uploads, and message splitting.

Discord

Uses discord.js for real-time messaging. Supports @mentions and DMs.

Telegram

Uses the Telegram Bot API (HTTPS) via native fetch and long-polling getUpdates. Zero external dependencies -- no webhook or public port needed. Supports @mentions, DMs, file uploads, message splitting, and per-topic sessions in forum supergroups.

Web

Embeddable chat widget for any webpage. Two modes: widget (floating bubble + popup panel) and embedded (fills a container div). Zero external dependencies -- served as a single <script> tag. Real-time streaming via WebSocket.

Note: The web widget has no built-in user authentication. It is designed for private networks, VPNs, or behind a reverse proxy with auth. See Security for details.

Deployment Model

OpenCode Chat Bridge runs as a bot service from a project checkout or container.

The operator installs the project dependencies, configures a connector, and runs its process. Each connector process serves its chat platform and can accept multiple users. Use allowedUsers to restrict access.

bun install installs the dependencies required by the bridge into the project checkout.

Quick Start

git clone https://github.com/ominiverdi/opencode-chat-bridge
cd opencode-chat-bridge
bun install  # Install project dependencies
cp .env.example .env  # Edit with your credentials
test -e chat-bridge.json || cp chat-bridge.json.example chat-bridge.json

Run a connector:

bun connectors/matrix.ts
bun connectors/slack.ts
bun connectors/whatsapp.ts
bun connectors/mattermost.ts
bun connectors/discord.ts
bun connectors/telegram.ts
bun connectors/web.ts

See setup guides: Matrix | Slack | Mattermost | WhatsApp | Discord | Telegram | Web. Signal is not currently supported; see Signal Status.

ACP Backends

OpenCode remains the default. To use another ACP v1 stdio agent, configure its command and arguments in chat-bridge.json:

{
  "sessionStorePath": "./state/acp-sessions.json",
  "acp": {
    "command": "/usr/bin/ferrum",
    "args": ["acp"],
    "backendId": "ferrum",
    "profileDir": "./profiles/ferrum-chat"
  }
}

The bridge creates a deterministic, collision-resistant workspace for every connector/thread. It copies the optional profile into that workspace, persists the ACP session ID with its canonical working directory and backend identity, resumes after restart, and removes the mapping and backend session on /clear. Keep credentials in the process environment, not the profile or session store. See Configuration.

Ferrum backend

Ferrum is a small Rust-native Linux coding agent that can run as an ACP v1 stdio backend:

ferrum acp

It is a good fit for chat bridge deployments that need fast startup, low runtime overhead, durable sessions, and tight tool policy. Ferrum supports JSONL session resume, AGENTS.md context loading, Agent Skills-style instruction packages, image input, OpenAI-compatible providers, ChatGPT/Codex OAuth, bounded built-in tools, and stdio MCP servers.

For public or semi-public rooms, use a dedicated Ferrum profile and expose narrow MCP servers instead of broad local authority. For example, deny shell and file mutation unless the bot explicitly needs them:

mcp_enabled = true

[tools]
deny = ["write", "edit", "bash"]

The bridge/Ferrum integration supports per-thread workspaces, streaming text/thought updates, command discovery, cancellation, restart-safe resume/delete, and restrictive workspace policy. See Configuration.

Docker

Run with Docker (no Bun/Node installation needed):

# Pull the image
docker pull lbecchi/opencode-chat-bridge

# Run a connector
docker run -e CONNECTOR=discord -e DISCORD_TOKEN=your_token lbecchi/opencode-chat-bridge
docker run -e CONNECTOR=slack -e SLACK_BOT_TOKEN=xoxb-... -e SLACK_APP_TOKEN=xapp-... lbecchi/opencode-chat-bridge
docker run -e CONNECTOR=matrix -e MATRIX_HOMESERVER=https://matrix.org -e MATRIX_USER_ID=@bot:matrix.org -e MATRIX_PASSWORD=... lbecchi/opencode-chat-bridge
docker run -e CONNECTOR=telegram -e TELEGRAM_BOT_TOKEN=110201543:AAH... lbecchi/opencode-chat-bridge

Or use docker-compose:

# Clone and configure
git clone https://github.com/ominiverdi/opencode-chat-bridge
cd opencode-chat-bridge
cp .env.example .env  # Edit with your credentials

# Run specific connectors
docker-compose up discord
docker-compose up slack matrix

# Run all connectors
docker-compose up

See docs/DOCKER_SETUP.md for detailed instructions.

Usage

Use the trigger prefix (default: !oc) or mention the bot:

!oc what time is it?
!oc what's the weather in Barcelona?
!oc /h             # Help
!oc /status        # Current chat session status
!oc /p             # List saved ACP projects/workdirs (if sessionPicker is enabled)
!oc /p 1           # Select a project/workdir
!oc /s             # List saved sessions in the selected project
!oc /s 2           # Switch to a saved session and show recent history
!oc /m 2           # Mirror a saved session read-only, checking every 60s
!oc /m             # Stop mirror mode
!oc /r             # Reload current session and show recent history
!oc /d             # Detach without deleting the saved backend session
!oc /clear         # Delete current session history

Session picker commands are disabled by default and require sessionPicker.enabled = true. On WhatsApp, bridge-local slash commands may also be sent bare for quicker mobile use when the session picker is enabled:

/h
/p
/p 1
/s
/s 2
/m 2
/m
/r
/d

OpenCode Commands

OpenCode's built-in commands are forwarded automatically:

!oc /init          # Initialize context with codebase summary
!oc /compact       # Compress conversation history
!oc /review        # Review recent changes

These appear in /help and are passed directly to OpenCode.

Permissions

OpenCode uses tools (functions) to perform actions. The opencode.json file controls which tools are allowed. A local file overrides your global config (~/.config/opencode/opencode.json).

Built-in tools:

For a public bot, deny these:

{
  "default_agent": "chat-bridge",
  "agent": {
    "chat-bridge": {
      "permission": {
        "read": "deny",
        "edit": "deny",
        "write": "deny",
        "bash": "deny",
        "glob": "deny",
        "grep": "deny",
        "task": "deny"
      }
    }
  }
}

MCP Servers

MCP servers provide additional tools. Add them in the mcp section, then allow their tools in permissions:

{
  "mcp": {
    "weather": {
      "command": ["npx", "-y", "open-meteo-mcp-lite"],
      "enabled": true
    }
  },

  "agent": {
    "chat-bridge": {
      "permission": {
        "weather_*": "