opencode-slack-agent

OpenCode plugin that connects Slack to your AI agent. Receives DMs and @mentions via Socket Mode, creates OpenCode sessions to process them, and sends responses back to Slack.

How It Works

opencode serve
  └─ [plugin: opencode-slack-agent]
       ├─ Plugin (Bun) — session management, OpenCode client, IPC
       └─ Socket Worker (Node) — Slack Socket Mode, message delivery
            ├─ DM or @mention received → IPC → plugin
            ├─ Plugin creates/reuses OpenCode session
            ├─ Streams tool progress (🔧) to Slack thread
            └─ Sends final response (or uploads file for long responses)

Setup

1. Create a Slack App

1. Go to api.slack.com/apps → Create New App → From scratch
2. Enable Socket Mode → generate App-Level Token (xapp-...) with scope connections:write
3. Add Bot Token Scopes (OAuth & Permissions):
   • im:read, im:write, im:history, channels:read, chat:write
   • reactions:write, reactions:read, files:read, files:write
4. Add Event Subscriptions (Subscribe to bot events):
   • message.im, app_mention
5. Install to Workspace → save Bot Token (xoxb-...)

2. Install the Plugin

opencode plugin opencode-slack-agent --global

3. Configure

Add plugin with tokens to ~/.config/opencode/opencode.json:

{
  "plugin": [
    ["opencode-slack-agent", {
      "SLACK_BOT_TOKEN": "xoxb-...",
      "SLACK_APP_TOKEN": "xapp-..."
    }]
  ]
}

Option	Default	Description
SLACK_BOT_TOKEN	—	Required. Bot token (xoxb-...)
SLACK_APP_TOKEN	—	Required. App-level token (xapp-...)
DEFAULT_DIRECTORY	serve directory	Default workspace for new sessions
ALLOWED_USERS	—	Comma-separated Slack user IDs or emails. If unset, everyone can use the bot
ATTACH_TIMEOUT_SEC	600	Timeout (seconds) for !attach bg_xxx polling. Reads plugin option first, then env var fallback. Invalid/non-positive values fall back to 600

4. Run

opencode serve --port 4096

Features

Thread-based Sessions (persistent)

• Each Slack thread = one OpenCode session
• Session persists across server restarts (slack-sessions.json)
• Thread replies continue the same conversation with full context

Multi-Agent Support

• @build fix the bug — use specific agent per message
• @plan analyze this project — plan mode
• @oracle review this design — read-only consultation
• No prefix → uses default or !agent setting

Real-time Streaming

• 🔧 Tool execution status shown in thread
• 💭 Reasoning/thinking (when model supports it)
• 📋 Todo/plan updates forwarded to Slack

Long Response Handling

• Responses > 3900 chars or with code blocks > 2000 chars → file upload (snippet)
• Markdown automatically converted to Slack mrkdwn format

Permission & Question Forwarding

• Agent permission requests → forwarded to Slack thread (1/2/3 to allow/always/reject)
• Agent questions → forwarded with options, reply to answer

Commands

Command	Description
!help	Show all commands
!model	Show current model
!model provider/model	Switch model
!model reset	Restore default model
!agent	Show current agent
!agent build	Switch agent
!agent reset	Restore default agent
!dir	Show current workspace
!dir /path/to/project	Change workspace
!attach ses_xxx	Attach existing session (URL paste supported)
!attach bg_xxx	Attach and poll a background task ID (bg_[A-Za-z0-9_-]+)
!reset	Reset current thread session

Architecture

Hybrid sidecar pattern:

1. Plugin (runs in OpenCode's Bun runtime)

   • Manages sessions via PluginInput.client (no HTTP)
   • Persistent session map (JSON file)
   • Permission/question handling
   • Markdown → Slack mrkdwn conversion
   • SSE event streaming for real-time updates

2. Socket Worker (spawned Node.js process)

   • Maintains Slack Socket Mode WebSocket (reliable in Node)
   • Handles chat.postMessage, reactions, files.uploadV2
   • Communicates with plugin via IPC

This separation exists because Bun's embedded runtime doesn't reliably handle WebSocket reconnections for Socket Mode.

Important

• Only one Socket Mode connection per app token at a time
• Environment variable SLACK_AGENT_ENABLED=false to disable without removing config

Development

git clone https://github.com/leecoder/opencode-slack-agent.git
cd opencode-slack-agent
npm install
npm run build

License

MIT