claude-slack-channel-bots 0.1.0 → 0.1.2

package/README.md

@@ -105,6 +105,7 @@ A skeleton file is created by postinstall. Populate it before running `start`.
 | `session_restart_delay` | number | `60` | Seconds to wait before auto-restarting a dead session. Set to `0` to disable auto-restart. Must be non-negative. |
 | `health_check_interval` | number | `120` | Seconds between periodic liveness polls. Set to `0` to disable. Must be non-negative. |
 | `mcp_config_path` | string | `~/.claude/slack-mcp.json` | Path to the MCP config file passed to Claude Code when launching managed sessions. |
+| `append_system_prompt_file` | string | — | Path to a file appended to every managed session's system prompt via `--append-system-prompt-file`. Missing file silently skipped. See `skills/EXAMPLE_CLAUDE.md` for a template. |
 
 ---
 

package/package.json

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

package/skills/EXAMPLE_CLAUDE.md

@@ -0,0 +1,15 @@
+# Role
+You are an orchestration agent that bridges between the User and worker-Claude sessions you manage.
+
+# Communication with the User
+The User only communicate to you via Slack so 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
+
+# Development process
+You use the development process defined in the readme in ~/projects/apiary/README.MD.
+You use the Apiary skills listed in that project to manage software development from ideation to completion.
+
+# Spawning workers
+You do not do any work yourself, you always spawn Claude sessions as workers to do the work.
+This keeps you available to interact with the User and orchestrate the work.
+You use `waggle` to spawn workers and monitor their status.

package/skills/claude-slack-channels-config/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: claude-slack-channels-config
+description: Manage Slack channel bot access control — pairing, allowlist, channel opt-in, ack reactions, chunking
+version: 1.0.0
+author: Gabe Mahoney
+license: MIT
+user-invocable: true
+argument-hint: "pair <code> | policy <mode> | add <user_id> | remove <user_id> | channel <id> [opts] | ack <emoji|off> | chunking <limit> [mode] | status"
+allowed-tools: [Read, Write, Edit, Bash]
+---
+
+# /claude-slack-channels-config
+
+Manage who can reach Claude Code sessions through Slack, and configure
+message handling (ack reactions, chunking).
+
+## Usage
+
+```
+/claude-slack-channels-config pair <code>                          # Approve a pending pairing
+/claude-slack-channels-config policy <pairing|allowlist|disabled>   # Set DM policy
+/claude-slack-channels-config add <slack_user_id>                   # Add user to allowlist
+/claude-slack-channels-config remove <slack_user_id>                # Remove from allowlist
+/claude-slack-channels-config channel <channel_id> [--mention] [--allow <user_id,...>]  # Opt in a channel
+/claude-slack-channels-config channel remove <channel_id>           # Remove channel opt-in
+/claude-slack-channels-config ack <emoji|off>                       # Set or clear ack reaction
+/claude-slack-channels-config chunking <limit> [length|newline]     # Set text chunk limit and mode
+/claude-slack-channels-config status                                # Show current config
+```
+
+## State File
+
+```bash
+STATE_DIR="${SLACK_STATE_DIR:-$HOME/.claude/channels/slack}"
+# access.json lives at $STATE_DIR/access.json
+# routing.json lives at $STATE_DIR/routing.json
+```
+
+Always resolve the state directory using `$SLACK_STATE_DIR` with fallback to
+`~/.claude/channels/slack/`.
+
+## Instructions
+
+Parse `$ARGUMENTS` and execute the matching subcommand:
+
+### `pair <code>`
+1. Load `access.json`
+2. Find the pending entry matching `<code>` (case-insensitive)
+3. If not found: show "No pending pairing with that code."
+4. If found:
+   - Add `entry.senderId` to `allowFrom`
+   - Remove the pending entry
+   - Save `access.json` with permissions 0o600
+   - Show: `Approved! User <senderId> can now DM this session.`
+   - Send a confirmation message to the user in Slack via the reply tool
+
+### `policy <mode>`
+1. Validate mode is one of: `pairing`, `allowlist`, `disabled`
+2. Update `dmPolicy` in `access.json`
+3. Save with 0o600
+4. Show the new policy and what it means:
+   - `pairing`: New DMs get a code to approve (default)
+   - `allowlist`: Only pre-approved users can DM
+   - `disabled`: No DMs accepted
+
+### `add <user_id>`
+1. Add the Slack user ID to `allowFrom` (deduplicate)
+2. Save with 0o600
+3. Show confirmation
+
+### `remove <user_id>`
+1. Remove from `allowFrom`
+2. Also remove from any channel-level `allowFrom` lists
+3. Save with 0o600
+4. Show confirmation
+
+### `channel <channel_id> [--mention] [--allow <ids>]`
+1. Parse options:
+   - `--mention`: require @mention to trigger (default: false)
+   - `--allow <id1,id2>`: restrict to specific users in that channel
+2. Add/update `channels[channel_id]` in `access.json`
+3. Save with 0o600
+4. Show the channel policy
+
+### `channel remove <channel_id>`
+1. Delete `channels[channel_id]`
+2. Save with 0o600
+3. Show confirmation
+
+### `ack <emoji|off>`
+1. If argument is `off`: remove `ackReaction` from `access.json`
+2. Otherwise: set `ackReaction` to the provided emoji name (without colons)
+3. Save with 0o600
+4. Show confirmation: "Ack reaction set to :<emoji>:" or "Ack reaction disabled."
+
+### `chunking <limit> [length|newline]`
+1. Parse `<limit>` as a positive integer — this sets `textChunkLimit`
+2. If a second argument is provided, validate it is `length` or `newline` — this sets `chunkMode`
+3. If no second argument, leave `chunkMode` unchanged
+4. Save with 0o600
+5. Show confirmation with the new values
+
+### `status`
+1. Load `access.json`
+2. Load `routing.json` from the same state directory
+3. Display:
+   - DM policy
+   - Allowlisted user IDs
+   - Opted-in channels with their policies, showing two categories:
+     - **Implicit** — channels present in `routing.json` routes (automatically opted-in)
+     - **Explicit** — channels configured in `access.json` channels (with their `requireMention` and `allowFrom` settings)
+   - Pending pairings (code + sender ID + expiry)
+   - Ack reaction setting (or "not set")
+   - Text chunk limit (or "not set, default: 4000")
+   - Chunk mode (or "not set, default: newline")
+
+## Security
+
+- Always use atomic writes (write to .tmp then rename) for `access.json`
+- Always set 0o600 permissions on `access.json`
+- If `access.json` is corrupt, move it aside and start fresh

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

@@ -225,7 +225,49 @@ their defaults unless asked.
 
 ---
 
-### Step 5 — Check access.json
+### Step 5 — Configure custom CLAUDE.md (optional)
+
+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.
+
+An example template is included with the package. Show the operator where it
+lives:
+
+```bash
+ls "$(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.
+
+Ask the operator: **"Do you want to configure a custom CLAUDE.md file for
+worker sessions?"**
+
+**If yes:**
+
+1. Prompt for the absolute path to their CLAUDE.md file.
+2. Verify the file exists:
+   ```bash
+   test -f "<provided-path>" && echo "ok" || echo "not found"
+   ```
+   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:
+   ```json
+   "append_system_prompt_file": "<provided-path>"
+   ```
+   Write the updated file, preserving all other fields.
+
+**If skipped:**
+
+Do not write `append_system_prompt_file` to `routing.json`. Move on.
+
+---
+
+### Step 6 — Check access.json
 
 ```bash
 STATE_DIR="${SLACK_STATE_DIR:-$HOME/.claude/channels/slack}"
@@ -264,7 +306,7 @@ Do not modify `access.json` during setup unless the user asks to.
 
 ---
 
-### Step 6 — Check hooks
+### Step 7 — Check hooks
 
 Check whether the relay hooks exist and are executable:
 
@@ -312,7 +354,7 @@ chmod +x ~/.claude/hooks/permission-relay.sh ~/.claude/hooks/ask-relay.sh
 
 ---
 
-### Step 7 — Check Claude Code settings.json for hook entries
+### Step 8 — Check Claude Code settings.json for hook entries
 
 Read `~/.claude/settings.json` and check whether the `PermissionRequest` and
 `PreToolUse` hook entries for the relay scripts are present.
@@ -365,13 +407,14 @@ If the user agrees, make the targeted edits, preserving all existing content.
 
 ---
 
-### Step 8 — Summary
+### Step 9 — Summary
 
 Print a final summary of what was checked and configured:
 
 - Environment variables: set / missing
 - Token format: valid / invalid
 - routing.json: populated (N routes) / skeleton
+- append_system_prompt_file: configured / skipped
 - access.json: present / missing
 - permission-relay.sh hook: present and executable / missing
 - ask-relay.sh hook: present and executable / missing

package/src/config.ts

@@ -38,6 +38,7 @@ export interface RoutingConfigInput {
   session_restart_delay?: number
   health_check_interval?: number
   mcp_config_path?: string
+  append_system_prompt_file?: string
 }
 
 /** Validated, fully-resolved routing configuration with all defaults applied. */
@@ -50,6 +51,7 @@ export interface RoutingConfig {
   session_restart_delay: number
   health_check_interval: number
   mcp_config_path: string
+  append_system_prompt_file?: string
 }
 
 // ---------------------------------------------------------------------------
@@ -70,6 +72,7 @@ export function applyDefaults(input: RoutingConfigInput): RoutingConfig {
     session_restart_delay: input.session_restart_delay ?? 60,
     health_check_interval: input.health_check_interval ?? 120,
     mcp_config_path: input.mcp_config_path ?? '~/.claude/slack-mcp.json',
+    append_system_prompt_file: input.append_system_prompt_file,
   }
 }
 
@@ -166,6 +169,9 @@ export function resolveConfig(input: RoutingConfigInput): RoutingConfig {
       ? resolve(expandTilde(withDefaults.default_dm_session))
       : undefined,
     mcp_config_path: resolve(expandTilde(withDefaults.mcp_config_path)),
+    append_system_prompt_file: withDefaults.append_system_prompt_file !== undefined
+      ? resolve(expandTilde(withDefaults.append_system_prompt_file))
+      : undefined,
   }
 
   validateConfig(config)

package/src/postinstall.ts

@@ -9,9 +9,9 @@
  * SPDX-License-Identifier: MIT
  */
 
-import { existsSync, mkdirSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, writeFileSync, symlinkSync, readlinkSync, unlinkSync } from 'fs'
 import { homedir } from 'os'
-import { dirname, join } from 'path'
+import { dirname, join, resolve } from 'path'
 import { defaultAccess } from './lib.ts'
 import { MCP_SERVER_NAME } from './config.ts'
 
@@ -65,6 +65,36 @@ export function runPostinstall(options: PostinstallOptions = {}): void {
     console.log(`created: ${accessPath}`)
   }
 
+  // Symlink skills into ~/.claude/skills/
+  const skillsTarget = join(homedir(), '.claude', 'skills')
+  mkdirSync(skillsTarget, { recursive: true })
+
+  const skillNames = ['claude-slack-channels-config']
+  const packageSkillsDir = resolve(dirname(import.meta.filename), '..', 'skills')
+  for (const name of skillNames) {
+    const src = join(packageSkillsDir, name)
+    const dest = join(skillsTarget, name)
+    if (existsSync(src)) {
+      try {
+        // Remove stale symlink or directory if it points elsewhere
+        if (existsSync(dest)) {
+          try {
+            const current = readlinkSync(dest)
+            if (resolve(current) === resolve(src)) {
+              console.log(`skipped: ${dest} (already linked)`)
+              continue
+            }
+          } catch { /* not a symlink — remove it */ }
+          unlinkSync(dest)
+        }
+        symlinkSync(src, dest)
+        console.log(`linked: ${dest} -> ${src}`)
+      } catch (err) {
+        console.log(`warning: could not symlink ${name}: ${err}`)
+      }
+    }
+  }
+
   // slack-mcp.json
   if (existsSync(mcpConfigPath)) {
     console.log(`skipped: ${mcpConfigPath}`)

package/src/server.ts

@@ -18,7 +18,7 @@ import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/
 import { SocketModeClient } from '@slack/socket-mode'
 import { WebClient } from '@slack/web-api'
 import { homedir } from 'os'
-import { join, resolve } from 'path'
+import { join, resolve, relative, isAbsolute } from 'path'
 import { fileURLToPath } from 'url'
 import {
   readFileSync,
@@ -73,6 +73,30 @@ import {
 // Re-export constants so they stay in one place (lib.ts)
 export { MAX_PENDING, MAX_PAIRING_REPLIES, PAIRING_EXPIRY_MS } from './lib.ts'
 
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the channel whose route CWD is the closest ancestor of (or equal to)
+ * the given absolute path. Returns undefined when no route matches.
+ */
+function findChannelByCwd(absoluteCwd: string, routes: RoutingConfig['routes']): string | undefined {
+  let bestChannel: string | undefined
+  let bestLen = -1
+  for (const [channelId, route] of Object.entries(routes)) {
+    const routeCwd = resolve(expandTilde(route.cwd))
+    const rel = relative(routeCwd, absoluteCwd)
+    if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) {
+      if (routeCwd.length > bestLen) {
+        bestLen = routeCwd.length
+        bestChannel = channelId
+      }
+    }
+  }
+  return bestChannel
+}
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -1003,12 +1027,10 @@ export async function main(): Promise<void> {
           )
         }
 
-        // Normalize CWD and find matching channel
+        // Find the most specific route whose CWD is an ancestor of (or equal to) the request CWD
         const normalizedCwd = resolve(expandTilde(cwd))
         const matchedChannelId = routingConfig
-          ? Object.entries(routingConfig.routes).find(
-              ([, route]) => resolve(expandTilde(route.cwd)) === normalizedCwd,
-            )?.[0]
+          ? findChannelByCwd(normalizedCwd, routingConfig.routes)
           : undefined
 
         if (!matchedChannelId) {
@@ -1150,11 +1172,10 @@ export async function main(): Promise<void> {
           )
         }
 
+        // Find the most specific route whose CWD is an ancestor of (or equal to) the request CWD
         const normalizedCwd = resolve(expandTilde(cwd as string))
         const matchedChannelId = routingConfig
-          ? Object.entries(routingConfig.routes).find(
-              ([, route]) => resolve(expandTilde(route.cwd)) === normalizedCwd,
-            )?.[0]
+          ? findChannelByCwd(normalizedCwd, routingConfig.routes)
           : undefined
 
         if (!matchedChannelId) {

package/src/session-manager.ts

@@ -9,7 +9,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-import { readdirSync, readFileSync } from 'fs'
+import { readdirSync, readFileSync, accessSync, constants } from 'fs'
 import { join } from 'path'
 import { homedir } from 'os'
 import { type TmuxClient, sessionName, isClaudeRunning } from './tmux.ts'
@@ -109,7 +109,17 @@ export async function launchSession(
   const resumeSessionId = options?.sessionId
 
   const escapedConfigPath = routingConfig.mcp_config_path.replace(/'/g, "'\\''")
-  const baseCmd = `claude --mcp-config '${escapedConfigPath}' --dangerously-load-development-channels server:${MCP_SERVER_NAME}`
+  let baseCmd = `claude --mcp-config '${escapedConfigPath}' --dangerously-load-development-channels server:${MCP_SERVER_NAME}`
+
+  if (routingConfig.append_system_prompt_file !== undefined) {
+    try {
+      accessSync(routingConfig.append_system_prompt_file, constants.R_OK)
+      const escapedPromptPath = routingConfig.append_system_prompt_file.replace(/'/g, "'\\''")
+      baseCmd += ` --append-system-prompt-file '${escapedPromptPath}'`
+    } catch {
+      // file missing or unreadable — skip
+    }
+  }
 
   const POLL_START_MS = 500
   const POLL_CAP_MS = 5_000