FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

leecoder/opencode-slack-agent: OpenCode Slack agent plugin — Socket Mode, SSE real-time streaming, persistent thread sessions, permission forwarding · GitHub

/ opencode-slack-agent Public
BranchesTags

Repository files navigation

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
DEFAULT_AGENT — Agent name to use for prompts in Slack threads. Reads plugin option first, then SLACK_DEFAULT_AGENT env var. Can be overridden per-message with @<agent> or per-thread with !agent; cleared by !agent reset. Useful when the global opencode default agent has an identity you don't want exposed in Slack (e.g., a chat-facing persona)
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

About

OpenCode Slack agent plugin — Socket Mode, SSE real-time streaming, persistent thread sessions, permission forwarding

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases

Contributors

Languages

Back | FazBrowse Home | New Git URL