claude-slack-channel-bots 0.4.0 → 0.4.2

package/README.md

@@ -1,4 +1,4 @@
-# Slack Channel Router
+# Claude Slack Channel Bots
 
 A single HTTP MCP server that holds one Slack Socket Mode connection and routes messages to multiple independent Claude Code sessions, each scoped to a different repo and reachable via its own Slack channel. Inbound messages are dispatched to whichever session owns the channel they arrived on; outbound tool calls are restricted to channels that session has previously received a message from.
 
@@ -58,6 +58,7 @@ Tokens and runtime options are read from environment variables. There is no `.en
 | `SLACK_APP_TOKEN` | Slack app-level token (`xapp-…`). Required. Generated under Basic Information → App-Level Tokens with the `connections:write` scope. |
 | `SLACK_STATE_DIR` | Override the directory where `routing.json`, `access.json`, and runtime state are stored. Defaults to `~/.claude/channels/slack`. |
 | `SLACK_ACCESS_MODE` | Set to `static` to load `access.json` once at startup and cache it for the lifetime of the process rather than re-reading it on every event. Useful in high-throughput environments where disk reads are a concern. |
+| `SLACK_DRY_RUN` | Set to `1` to start the server without Slack credentials. Token validation is skipped, Socket Mode and `web.auth.test()` are not called, and MCP tool calls (`reply`, `react`, etc.) are logged instead of sent. Useful for integration testing. |
 
 Shell profile example:
 
@@ -67,6 +68,8 @@ export SLACK_APP_TOKEN=xapp-your-app-token
 # Optional overrides:
 export SLACK_STATE_DIR=~/.config/slack-channel-bots
 export SLACK_ACCESS_MODE=static
+# Dry-run mode (no Slack credentials needed):
+export SLACK_DRY_RUN=1
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-slack-channel-bots",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Multi-session Slack-to-Claude bridge \u2014 run multiple Claude Code bots across Slack channels via Socket Mode",
   "type": "module",
   "bin": {

package/skills/setup-slack-channel-bots/SKILL.md

@@ -227,45 +227,67 @@ their defaults unless asked.
 
 ---
 
-### Step 5 — Configure custom CLAUDE.md (optional)
+### Step 5 — Configure custom system prompt for worker sessions
 
-Worker sessions launched by the server can receive a custom system-prompt
-append via `append_system_prompt_file` in `routing.json`. This is useful for
-giving all workers project-specific instructions: communication rules,
-development process, how to spawn sub-workers, and so on.
+Worker sessions launched by the server can receive a custom system prompt
+via `append_system_prompt_file` in `routing.json`. This controls how the
+bots behave — their role, communication style, and capabilities.
 
-An example template is included with the package. Show the operator where it
-lives:
+**This is important.** Without a system prompt, bots won't know to communicate
+via Slack and will try to use the TUI (which nobody can see).
+
+An example template is included with the package. Read it for reference:
 
 ```bash
-ls "$(npm root -g)/claude-slack-channel-bots/skills/EXAMPLE_CLAUDE.md" 2>/dev/null \
+cat "$(npm root -g)/claude-slack-channel-bots/skills/EXAMPLE_CLAUDE.md" 2>/dev/null \
   || echo "NOT_FOUND"
 ```
 
-If the file is found, print its path so the operator can inspect it as a
-starting point.
+Show the user the example content so they understand what a system prompt
+looks like.
+
+Then ask: **"What should your bots do? Describe the role you want them to
+play, how they should communicate, and any specific behaviors."**
+
+Examples to offer if they're unsure:
+- "I want a coding assistant that responds to my messages in Slack"
+- "I want an orchestrator that manages workers and reports status"
+- "I want a simple bot that answers questions about my codebase"
+
+**After the user describes what they want:**
 
-Ask the operator: **"Do you want to configure a custom CLAUDE.md file for
-worker sessions?"**
+1. Write a system prompt file based on their description. The file MUST
+   always include these two essential sections at the top (adapt the wording
+   to match their described role):
 
-**If yes:**
+   ```markdown
+   # Communication with the User
+   The User communicates with you via Slack. Always use the
+   mcp__slack-channel-router__reply tool to send messages.
+   **Important**: Nothing you send to the TUI will be seen by the User.
+   ```
+
+   Then add sections based on what the user described (role, process,
+   capabilities, tone, etc.).
 
-1. Prompt for the absolute path to their CLAUDE.md file.
-2. Verify the file exists:
+2. Save the file to `~/.claude/channels/slack/system-prompt.md`:
    ```bash
-   test -f "<provided-path>" && echo "ok" || echo "not found"
+   STATE_DIR="${SLACK_STATE_DIR:-$HOME/.claude/channels/slack}"
    ```
-   Expand `~` before checking. If the file does not exist, warn the operator
-   and re-prompt until a valid path is given or they choose to skip.
-3. Read `routing.json`, add or update the top-level field:
+
+3. Read `routing.json`, add or update:
    ```json
-   "append_system_prompt_file": "<provided-path>"
+   "append_system_prompt_file": "~/.claude/channels/slack/system-prompt.md"
    ```
    Write the updated file, preserving all other fields.
 
-**If skipped:**
+4. Show the user what was written and ask if they want to make changes.
+   Iterate until they're happy.
+
+**If the user explicitly skips:**
 
-Do not write `append_system_prompt_file` to `routing.json`. Move on.
+Do not write `append_system_prompt_file` to `routing.json`, but warn them
+that bots won't know to communicate via Slack without a system prompt.
 
 ---
 

package/src/cli.ts

@@ -18,6 +18,7 @@ import { defaultTmuxClient, isClaudeRunning as tmuxIsClaudeRunning, sessionName
 import { readSessions, type SessionsMap } from './sessions.ts'
 import { loadConfig as configLoadConfig, type RoutingConfig } from './config.ts'
 import { initLogging } from './logging.ts'
+import { isDryRun } from './tokens.ts'
 
 // ---------------------------------------------------------------------------
 // Injectable dependency interface
@@ -92,14 +93,16 @@ export function createCli(deps: CliDeps): CliHandlers {
       deps.exit(1)
     }
 
-    // Check required Slack tokens
-    if (!deps.env['SLACK_BOT_TOKEN']) {
-      console.error('missing prerequisite: SLACK_BOT_TOKEN environment variable')
-      deps.exit(1)
-    }
-    if (!deps.env['SLACK_APP_TOKEN']) {
-      console.error('missing prerequisite: SLACK_APP_TOKEN environment variable')
-      deps.exit(1)
+    // Check required Slack tokens (skipped in dry-run mode)
+    if (!isDryRun()) {
+      if (!deps.env['SLACK_BOT_TOKEN']) {
+        console.error('missing prerequisite: SLACK_BOT_TOKEN environment variable')
+        deps.exit(1)
+      }
+      if (!deps.env['SLACK_APP_TOKEN']) {
+        console.error('missing prerequisite: SLACK_APP_TOKEN environment variable')
+        deps.exit(1)
+      }
     }
 
     // Check routing.json exists

package/src/lib.ts

@@ -189,8 +189,8 @@ export interface GateOptions {
 export async function gate(event: unknown, opts: GateOptions): Promise<GateResult> {
   const ev = event as Record<string, unknown>
 
-  // 1. Drop bot messages immediately
-  if (ev['bot_id']) return { action: 'drop' }
+  // 1. Drop our own bot messages (but allow messages from other bots)
+  if (ev['bot_id'] && ev['user'] === opts.botUserId) return { action: 'drop' }
 
   // 2. Drop non-message subtypes (message_changed, message_deleted, etc.)
   if (ev['subtype'] && ev['subtype'] !== 'file_share') return { action: 'drop' }

package/src/registry.ts

@@ -15,6 +15,7 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js'
 import { MCP_SERVER_NAME, type RoutingConfig } from './config.ts'
+import { isDryRun } from './tokens.ts'
 import { getPeerPidByPort, getSessionIdForPid } from './peer-pid.ts'
 import { readSessions, writeSessions, type SessionsMap } from './sessions.ts'
 
@@ -516,6 +517,11 @@ export function createSessionServer(
         // Per-session outbound gate (t2.c1r.zk.qm)
         assertOutboundAllowed(chatId, entry.deliveredChannels)
 
+        if (isDryRun()) {
+          console.error(`[slack] dry-run: reply to ${chatId} (${text.length} chars)`)
+          return { content: [{ type: 'text', text: `[dry-run] Would send message to ${chatId}` }] }
+        }
+
         const access = getAccess()
         const limit = access.textChunkLimit || DEFAULT_CHUNK_LIMIT
         const mode = access.chunkMode || 'newline'
@@ -575,6 +581,10 @@ export function createSessionServer(
       // ---------------------------------------------------------------------
       case 'react': {
         assertOutboundAllowed(args.chat_id, entry.deliveredChannels)
+        if (isDryRun()) {
+          console.error(`[slack] dry-run: react :${args.emoji}: on ${args.message_id}`)
+          return { content: [{ type: 'text', text: `[dry-run] Would react :${args.emoji}: to ${args.message_id}` }] }
+        }
         await web.reactions.add({
           channel: args.chat_id,
           timestamp: args.message_id,
@@ -590,6 +600,10 @@ export function createSessionServer(
       // ---------------------------------------------------------------------
       case 'edit_message': {
         assertOutboundAllowed(args.chat_id, entry.deliveredChannels)
+        if (isDryRun()) {
+          console.error(`[slack] dry-run: edit_message ${args.message_id} in ${args.chat_id}`)
+          return { content: [{ type: 'text', text: `[dry-run] Would edit message ${args.message_id}` }] }
+        }
         await web.chat.update({
           channel: args.chat_id,
           ts: args.message_id,
@@ -605,6 +619,10 @@ export function createSessionServer(
       // ---------------------------------------------------------------------
       case 'fetch_messages': {
         assertOutboundAllowed(args.channel, entry.deliveredChannels)
+        if (isDryRun()) {
+          console.error(`[slack] dry-run: fetch_messages from ${args.channel}`)
+          return { content: [{ type: 'text', text: `[dry-run] Would fetch messages from ${args.channel}` }] }
+        }
         const channel: string = args.channel
         const limit = Math.min(args.limit || 20, 100)
         const threadTs: string | undefined = args.thread_ts
@@ -646,6 +664,10 @@ export function createSessionServer(
       // ---------------------------------------------------------------------
       case 'download_attachment': {
         assertOutboundAllowed(args.chat_id, entry.deliveredChannels)
+        if (isDryRun()) {
+          console.error(`[slack] dry-run: download_attachment from ${args.chat_id} msg=${args.message_id}`)
+          return { content: [{ type: 'text', text: `[dry-run] Would download attachments from ${args.message_id}` }] }
+        }
         const channel: string = args.chat_id
         const messageTs: string = args.message_id
 

package/src/server.ts

@@ -52,7 +52,7 @@ import {
   hasReachedMaxFailures,
 } from './restart.ts'
 import { initHealthCheck, startHealthCheck, stopHealthCheck } from './health-check.ts'
-import { loadTokens } from './tokens.ts'
+import { loadTokens, isDryRun } from './tokens.ts'
 import { checkPidConflict, writePidFile, removePidFile } from './pid.ts'
 import { trackAck, consumeAck } from './ack-tracker.ts'
 import {
@@ -947,17 +947,22 @@ export async function main(): Promise<void> {
     }
   }
 
-  // Resolve bot user ID
-  try {
-    const auth = await web.auth.test()
-    botUserId = (auth.user_id as string) || ''
-  } catch (err) {
-    console.error('[slack] Failed to resolve bot user ID:', err)
-  }
+  if (isDryRun()) {
+    console.error('[slack] Running in dry-run mode — Slack disabled')
+    botUserId = 'U000DRY'
+  } else {
+    // Resolve bot user ID
+    try {
+      const auth = await web.auth.test()
+      botUserId = (auth.user_id as string) || ''
+    } catch (err) {
+      console.error('[slack] Failed to resolve bot user ID:', err)
+    }
 
-  // Connect Socket Mode
-  await socket.start()
-  console.error('[slack] Socket Mode connected')
+    // Connect Socket Mode
+    await socket.start()
+    console.error('[slack] Socket Mode connected')
+  }
 
   // Propagate resolved port to tool deps for peer PID discovery
   sessionToolDeps.serverPort = mcpPort
@@ -1104,6 +1109,17 @@ export async function main(): Promise<void> {
         // Generate unique request ID
         const requestId = crypto.randomUUID()
 
+        // Register pending entry BEFORE posting to Slack to avoid race condition:
+        // If the user clicks Allow/Deny before postMessage returns, the interactive
+        // handler needs the entry to already exist in pendingPermissions.
+        pendingPermissions.set(requestId, {
+          requestId,
+          channelId: matchedChannelId,
+          messageTs: '',
+          toolName: tool_name,
+          waiters: [],
+        })
+
         // Post Block Kit message to channel
         let messageTs: string
         try {
@@ -1115,6 +1131,7 @@ export async function main(): Promise<void> {
           })
           messageTs = postResult.ts as string
         } catch (err) {
+          pendingPermissions.delete(requestId)
           console.error('[slack] /permission: chat.postMessage failed:', err)
           return new Response(JSON.stringify({ error: 'Failed to post message' }), {
             status: 500,
@@ -1122,14 +1139,9 @@ export async function main(): Promise<void> {
           })
         }
 
-        // Register pending entry with empty waiters array
-        pendingPermissions.set(requestId, {
-          requestId,
-          channelId: matchedChannelId,
-          messageTs,
-          toolName: tool_name,
-          waiters: [],
-        })
+        // Update with the real message timestamp (needed for chat.update on decision)
+        const pending = pendingPermissions.get(requestId)
+        if (pending) pending.messageTs = messageTs
 
         return new Response(JSON.stringify({ requestId }), {
           status: 200,
@@ -1269,6 +1281,17 @@ export async function main(): Promise<void> {
           },
         ]
 
+        // Register pending entry BEFORE posting to Slack to avoid race condition:
+        // If the user clicks a button before postMessage returns, the interactive
+        // handler needs the entry to already exist in pendingQuestions.
+        pendingQuestions.set(requestId, {
+          requestId,
+          channelId: matchedChannelId,
+          messageTs: '',
+          question: question as string,
+          waiters: [],
+        })
+
         let messageTs: string
         try {
           const postResult = await web.chat.postMessage({
@@ -1278,6 +1301,7 @@ export async function main(): Promise<void> {
           })
           messageTs = postResult.ts as string
         } catch (err) {
+          pendingQuestions.delete(requestId)
           console.error('[slack] /ask: chat.postMessage failed:', err)
           return new Response(JSON.stringify({ error: 'Failed to post message' }), {
             status: 500,
@@ -1285,13 +1309,9 @@ export async function main(): Promise<void> {
           })
         }
 
-        pendingQuestions.set(requestId, {
-          requestId,
-          channelId: matchedChannelId,
-          messageTs,
-          question: question as string,
-          waiters: [],
-        })
+        // Update with the real message timestamp
+        const pendingQ = pendingQuestions.get(requestId)
+        if (pendingQ) pendingQ.messageTs = messageTs
 
         return new Response(JSON.stringify({ requestId }), {
           status: 200,

package/src/tokens.ts

@@ -7,11 +7,24 @@
  * SPDX-License-Identifier: MIT
  */
 
+// ---------------------------------------------------------------------------
+// Dry-run detection
+// ---------------------------------------------------------------------------
+
+export function isDryRun(): boolean {
+  const val = (process.env['SLACK_DRY_RUN'] ?? '').toLowerCase()
+  return val === '1' || val === 'true' || val === 'yes'
+}
+
 // ---------------------------------------------------------------------------
 // Token loading
 // ---------------------------------------------------------------------------
 
 export function loadTokens(): { botToken: string; appToken: string } {
+  if (isDryRun()) {
+    return { botToken: 'xoxb-dry-run', appToken: 'xapp-dry-run' }
+  }
+
   const botToken = process.env['SLACK_BOT_TOKEN'] ?? ''
   const appToken = process.env['SLACK_APP_TOKEN'] ?? ''