Skip to content

README.md

Latest commit

 

History

History
279 lines (200 loc) · 9.15 KB

README.md

File metadata and controls

279 lines (200 loc) · 9.15 KB

opencode-slack-plugin

OpenCode plugin that connects to Slack via Socket Mode. Run it as part of your opencode serve process — zero port exposure, no separate bot process needed.

Architecture

Your machine (MacBook / Linux / K8s Pod)
+----------------------------------------------+
|  opencode serve                               |
|    +-- plugins/                               |
|          +-- opencode-slack-plugin             |
|                |                              |
|                |  WebSocket (outbound only)    |
|                v                              |
|          Slack Socket Mode API                |
|                                               |
|          Zero ports exposed                   |
+----------------------------------------------+
  • The plugin runs inside the OpenCode process
  • Connects to Slack via Socket Mode (outbound WebSocket, no public URL)
  • Each Slack thread maps to an independent OpenCode session
  • Tool call progress and permission requests are forwarded to Slack in real time

Setup

1. Create a Slack App

  1. Go to api.slack.com/apps and click Create New App > From scratch
  2. Enable Socket Mode (sidebar > Socket Mode > toggle ON)
    • Generate an App-Level Token with scope connections:write
    • Copy the xapp-... token — this is your SLACK_APP_TOKEN
  3. Add Bot Token Scopes (sidebar > OAuth & Permissions > Scopes):
    • chat:write
    • app_mentions:read
    • channels:history
    • groups:history
    • im:history
  4. Subscribe to Bot Events (sidebar > Event Subscriptions > toggle ON):
    • app_mention
    • message.im
  5. Enable App Home > Messages Tab (check "Allow users to send Slash commands and messages from the messages tab")
  6. Install to Workspace and copy the xoxb-... Bot Token — this is your SLACK_BOT_TOKEN

2. Install the Plugin

From npm

Add to your opencode.json:

{
  "plugin": ["@kubeopencode/opencode-slack-plugin"]
}

Local install

Copy the built output or the source file into your OpenCode plugins directory:

# Option A: copy source directly
cp src/index.ts ~/.config/opencode/plugins/opencode-slack.ts

# Option B: build and copy dist
npm run build
cp dist/index.js ~/.config/opencode/plugins/opencode-slack.js

Then add dependencies to ~/.config/opencode/package.json:

{
  "dependencies": {
    "@slack/socket-mode": "^2.0.5",
    "@slack/web-api": "^7.13.0"
  }
}

3. Configure Environment Variables

export SLACK_BOT_TOKEN=xoxb-your-bot-token
export SLACK_APP_TOKEN=xapp-your-app-token

4. Run OpenCode

TUI mode (interactive terminal — plugin loads automatically):

opencode

Serve mode (headless server — plugin loads on first request):

opencode serve uses lazy instance loading — plugins only initialize when the first HTTP request arrives for a project directory. In KubeOpenCode, the Kubernetes StartupProbe (GET /session/status) triggers this automatically. For local testing, send a warmup request manually:

# Start the server
opencode serve &

# Send a warmup request to trigger plugin loading
sleep 1 && curl -s "http://127.0.0.1:4096/session/status?directory=$(pwd)" > /dev/null

# The server is now running with Slack connected.
# Look for "[slack-plugin] Slack Socket Mode connected" in the output.

The plugin activates automatically when both SLACK_BOT_TOKEN and SLACK_APP_TOKEN are set. If either is missing, the plugin silently skips initialization.

Usage

  • DM the bot directly for private conversations
  • @mention the bot in a channel to start a threaded conversation
  • Each Slack thread creates a separate OpenCode session with its own context

Permission Requests

When OpenCode needs permission (e.g., to write a file), the request is forwarded to the Slack thread:

Permission Request
write file
Pattern: src/index.ts

1. Yes (once)
2. Always
3. No (reject)

Reply: 1/y/yes, 2/always, or 3/n/no

Reply with the corresponding number or keyword.

Tool Updates

Completed tool calls are posted to the thread in real time:

*file_write* - wrote src/index.ts
*bash* - ran tests

Debugging

Log Locations

The plugin produces two categories of logs:

Source Location Contents
OpenCode structured log ~/.local/share/opencode/log/ Session lifecycle, LLM calls, tool execution, permission events, errors. File per startup, 10 most recent retained.
Plugin console output OpenCode process stdout/stderr [slack-plugin] prefixed messages: connection status, session creation, typing indicators, prompt results.

To find the current log directory:

opencode debug paths   # prints all paths including "log"

On macOS the default is ~/.local/share/opencode/log/. On Linux it follows $XDG_DATA_HOME/opencode/log/.

Investigating a Failed Slack Message

When a Slack message gets no reply, follow this sequence:

1. Find the session ID — look for [slack-plugin] Created session in stdout, or find the session by thread timestamp:

grep "Slack thread" ~/.local/share/opencode/log/2026-05-08T*.log

2. Trace the session in the structured log — search for the session ID to see the full lifecycle:

grep "ses_XXXXX" ~/.local/share/opencode/log/2026-05-08T*.log

Key events to look for:

Log entry Meaning
service=session ... created Session was created successfully
service=session.prompt step=0 loop LLM prompt loop started
service=llm ... stream LLM call initiated
service=llm ... stream error LLM call failed (check error= field)
service=session.processor ... error= Processor crashed while handling LLM response
service=session.prompt ... exiting loop Prompt completed normally
service=permission ... evaluated Permission was auto-resolved or user-replied

3. Check for LLM provider errors — filter for ERROR level:

grep "ERROR.*ses_XXXXX" ~/.local/share/opencode/log/2026-05-08T*.log

Common Failure Modes

Bot shows "is thinking..." but never replies:

The plugin's session.prompt() returned data with no text parts. This happens when the LLM provider fails. Check the structured log for stream error — common causes:

  • OAuth token expired (Google Vertex): POST https://oauth2.googleapis.com/token fails. Fix: gcloud auth application-default login
  • Proxy misconfiguration: The LLM provider's HTTP client inherits http_proxy/https_proxy env vars. If your proxy is down, LLM calls fail silently.
  • Rate limiting: Look for HTTP 429 in the error JSON.

Bot creates a session but the second message in the thread is ignored:

The thread requires @mention for each message in channel threads (by design — prevents capturing human-to-human conversation). DMs do not require @mention.

"Session idle" appears in stdout but no Slack message:

This means session.prompt() completed but returned empty text parts. Search the structured log for ERROR entries on that session ID to find the root cause.

Enabling Verbose Logging

# Print logs to stderr instead of file (useful for local debugging)
opencode serve --print-logs

# Set log level to DEBUG for maximum detail
opencode serve --log-level DEBUG

KubeOpenCode Integration

When running inside a KubeOpenCode Agent, the plugin additionally:

  • Heartbeat: Patches the kubeopencode.io/last-connection-active annotation to prevent standby auto-suspend while Slack conversations are active
  • Graceful shutdown: Disconnects cleanly when the OpenCode server is disposed

Deploy via the Agent spec:

apiVersion: kubeopencode.io/v1alpha1
kind: Agent
metadata:
  name: my-agent
spec:
  plugins:
    - name: "opencode-slack-plugin"
  credentials:
    - secretRef:
        name: slack-credentials   # Secret with SLACK_BOT_TOKEN and SLACK_APP_TOKEN

The heartbeat requires AGENT_NAME and AGENT_NAMESPACE env vars (auto-injected by the controller) and a ServiceAccount with RBAC permission to patch Agent resources. If any of these are missing, heartbeat is silently disabled.

Environment Variables

Variable Required Description
SLACK_BOT_TOKEN Yes Bot User OAuth Token (xoxb-...)
SLACK_APP_TOKEN Yes App-Level Token for Socket Mode (xapp-...)
AGENT_NAME No KubeOpenCode Agent name (for heartbeat, auto-injected)
AGENT_NAMESPACE No KubeOpenCode Agent namespace (for heartbeat, auto-injected)

How It Differs from @opencode-ai/slack

This plugin @opencode-ai/slack
Architecture Runs inside OpenCode process Separate Node.js process
Communication Internal function calls (no HTTP) HTTP to OpenCode server
Deployment Just opencode serve Must run bot + server separately
Port exposure Zero OpenCode server port (at least localhost)
Install Add to opencode.json plugins bun run packages/slack
K8s heartbeat Yes (prevents standby auto-suspend) No
Graceful shutdown Yes (listens for server.instance.disposed) No

License

MIT