slack

# Slack Skill Full Slack workspace integration with three modes: 1. **Scripts** — 9 Python scripts for on-demand Slack operations 2. **Session Bridge** — connect THIS Claude Code session to Slack (background listener + inbox file, no extra API costs) 3. **Unified Launcher** — `claudicle.py` with Claude Agent SDK, soul engine, per-channel sessions (requires SDK API key) ## When to Use This Skill ### Scripts (on-demand) - Posting messages to Slack channels or threads (with optional AI feedback buttons) - Reading channel history or thread replies - Searching messages, files, channels, or users via RTS API (with legacy fallback) - Streaming messages in real-time via chat streaming API - Adding or managing reactions on messages - Uploading files or code snippets - Listing channels, getting channel info, or joining channels (including bulk join) - Looking up users by name, ID, or email ### Session Bridge (recommended) - Connecting any running Claude Code session to Slack - Responding to @mentions and DMs with full tool access (this session IS the brain) - No extra API costs — messages processed in the current session context - Auto-notification of new messages via UserPromptSubmit hook - Personality as Claudicle via soul.md instructions (no XML machinery needed) ### Unified Launcher (persistent, requires SDK API key) - Running Claudicle as an interactive terminal + Slack bot in one process - Responding to @mentions and DMs in real time as "Claudicle, Artifex Maximus" - Multi-turn conversations in threads (per-channel session continuity via Claude Agent SDK) - Per-user personality modeling (learns communication style, interests, expertise) - Cross-thread soul state (tracks current project, task, topic, emotional state) - Three-tier memory: working memory (per-thread), user models (per-user), soul memory (global) - All Slack activity visible in terminal alongside direct terminal interactions ## Prerequisites All scripts require the `SLACK_BOT_TOKEN` environment variable (a Bot User OAuth Token starting with `xoxb-`). Scripts also require `requests` (`uv pip install --system requests`). Optional: `SLACK_USER_TOKEN` (`xoxp-`) enables workspace-wide search via legacy `search.messages`/`search.files` when the RTS API is unavailable. The bot token is used for all other operations. ```bash # Verify tokens echo $SLACK_BOT_TOKEN echo $SLACK_USER_TOKEN # optional, for legacy search fallback ``` ### First-Time Setup 1. Go to [api.slack.com/apps](https://api.slack.com/apps) → Create New App → From Scratch 2. Name it "Claude Code" → select your workspace 3. **OAuth & Permissions** → Bot Token Scopes → add all: - `app_mentions:read` - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `im:write` - `channels:join` — enables bot to join public channels programmatically - `chat:write` - `files:write`, `files:read` - `reactions:write`, `reactions:read` - `search:read` — legacy search (bot-visible channels only) - `search:read.public`, `search:read.private`, `search:read.im`, `search:read.mpim`, `search:read.files`, `search:read.users` — RTS API (unified search, Feb 2026+) - `users:read`, `users:read.email` - `users:write` (optional — enables green presence dot) 4. **Settings → Socket Mode** → toggle **ON** → generate an App-Level Token: - Name: `socket-mode` - Scope: `connections:write` - Copy the `xapp-` token 5. **Event Subscriptions** → toggle **ON** (no Request URL needed with Socket Mode) → **Subscribe to Bot Events** → add: - `app_mention` — channel @mentions - `message.im` — direct messages (required for DMs to work) - `app_home_opened` — App Home tab rendering 6. **App Home** → Show Tabs → enable **"Allow users to send Slash commands and messages from the messages tab"** 7. **Install to Workspace** → approve permissions → copy Bot User OAuth Token 8. Set environment variables (add to shell profile): ```bash export SLACK_BOT_TOKEN=xoxb-... # Bot User OAuth Token export SLACK_APP_TOKEN=xapp-... # App-Level Token (Socket Mode) export SLACK_USER_TOKEN=xoxp-... # (optional) User Token for legacy workspace-wide search ``` 9. Invite the bot to channels: `/invite @Claude Code` **After any scope or event subscription change**: reinstall the app (Install App → Reinstall to Workspace) and restart the launcher. --- ## Quick Start ```bash # Post a message python3 ~/.claude/skills/slack/scripts/slack_post.py "#general" "Hello from Claude" # Post with AI feedback buttons python3 ~/.claude/skills/slack/scripts/slack_post.py "#general" "Here's my analysis" --ai # Read recent messages python3 ~/.claude/skills/slack/scripts/slack_read.py "#general" -n 10 # Search the workspace (auto-detects RTS API, falls back to legacy) python3 ~/.claude/skills/slack/scripts/slack_search.py "deployment status" # Search with RTS API (messages, files, channels, users) python3 ~/.claude/skills/slack/scripts/slack_search.py "deployment" --rts --type channels # Stream a message in real-time python3 ~/.claude/skills/slack/scripts/slack_stream.py "#general" "Streaming message..." # Join all public channels python3 ~/.claude/skills/slack/scripts/slack_channels.py --join-all-public # Connect this session to Slack (recommended) cd ~/.claude/skills/slack/daemon && python3 slack_listen.py --bg python3 ~/.claude/skills/slack/scripts/slack_check.py # Start the unified launcher (requires SDK API key) cd ~/.claude/skills/slack/daemon && python3 claudicle.py ``` --- ## Session Bridge (Recommended) Connect any running Claude Code session to Slack. A background listener catches @mentions and DMs → `inbox.jsonl`. This session reads the inbox, processes with full tool access, posts responses back. No extra API costs. ```bash # Connect cd ~/.claude/skills/slack/daemon && python3 slack_listen.py --bg # Check messages python3 ~/.claude/skills/slack/scripts/slack_check.py # Respond to thread, remove hourglass, mark handled python3 ~/.claude/skills/slack/scripts/slack_post.py "C12345" "response" --thread "TS" python3 ~/.claude/skills/slack/scripts/slack_react.py "C12345" "TS" "hourglass_flowing_sand" --remove python3 ~/.claude/skills/slack/scripts/slack_check.py --ack 1 # Disconnect python3 ~/.claude/skills/slack/daemon/slack_listen.py --stop ``` **Soul Formatter** (optional): `scripts/slack_format.py` adds Open Souls cognitive step formatting — perception framing, dialogue extraction, monologue logging. ```bash python3 slack_format.py perception "Tom" "What's the status?" # → Tom said, "..." echo "$raw" | python3 slack_format.py extract # → external dialogue only echo "$raw" | python3 slack_format.py extract --narrate --log # → narrated + logged python3 slack_format.py instructions # → cognitive step XML format ``` **Automated Respond**: `/slack-respond` processes all pending messages as Claudicle with full cognitive steps — perception, monologue, dialogue, post, ack — in a single invocation. See `~/.claude/skills/slack-respond/SKILL.md`. **Soul Activation**: `/ensoul` activates the Claudicle identity in any Claude Code session with persistent soul.md injection through compaction/resume. `/slack-sync #channel` then binds the ensouled session to a Slack channel. Both are opt-in per session. The soul registry (`~/.claude/hooks/soul-registry.py`) tracks all active sessions and their channel bindings — ensouled or not. For full installation, architecture, inbox format, auto-notification hook, and troubleshooting, see `references/session-bridge.md`. **App Home**: The Home tab renders automatically when a user opens Claudicle's profile (via `app_home_opened` in the listener). Shows live status, toolkit, cognitive architecture, memory system. Refresh manually: ```bash python3 ~/.claude/skills/slack/scripts/slack_app_home.py "USER_ID" python3 ~/.claude/skills/slack/scripts/slack_app_home.py --all python3 ~/.claude/skills/slack/scripts/slack_app_home.py --debug # print blocks, no publish ``` --- ## Script Selection Guide | Task | Script | Example | |------|--------|---------| | Post a message | `slack_post.py` | `slack_post.py "#general" "Hello"` | | Reply to a thread | `slack_post.py` | `slack_post.py "#ch" "reply" --thread TS` | | Schedule a message | `slack_post.py` | `slack_post.py "#ch" "msg" --schedule ISO` | | Read channel history | `slack_read.py` | `slack_read.py "#general" -n 20` | | Read thread | `slack_read.py` | `slack_read.py "#ch" --thread TS` | | Search (RTS, auto) | `slack_search.py` | `slack_search.py "query"` | | Search messages only | `slack_search.py` | `slack_search.py "query" --type messages` | | Search files | `slack_search.py` | `slack_search.py "query" --files` | | Search channels/users | `slack_search.py` | `slack_search.py "query" --rts --type channels` | | Stream a message | `slack_stream.py` | `slack_stream.py "#ch" "text" --chunk-size 50` | | Stream from stdin | `slack_stream.py` | `echo "text" \| slack_stream.py "#ch" --stdin` | | Post with AI buttons | `slack_post.py` | `slack_post.py "#ch" "msg" --ai` | | Delete message | `slack_delete.py` | `slack_delete.py "#ch" TS1 TS2` | | Clean thread (bot msgs) | `slack_delete.py` | `slack_delete.py "#ch" --thread TS` | | Add reaction | `slack_react.py` | `slack_react.py "#ch" TS emoji` | | Upload file | `slack_upload.py` | `slack_upload.py "#ch" ./file.pdf` | | Share code snippet | `slack_upload.py` | `slack_upload.py "#ch" --snippet CODE` | | List channels | `slack_channels.py` | `slack_channels.py` | | Join channel | `slack_channels.py` | `slack_channels.py --join "#ch"` | | Join all public channels | `slack_channels.py` | `slack_channels.py --join-all-public` | | Find user by email | `slack_users.py` | `slack_users.py --email user@co.com` | For full script documentation (all parameters, examples, test suite, common workflows), see `references/scripts-reference.md`. --- ## Rate Limit Awareness | Tier | Rate | Key Methods | |------|------|-------------| | **Tier 1** | **1/min** | `conversations.history`, `conversations.replies` | | Tier 2 | 20/min | `conversations.list`, `users.list`, `search.messages`, `assistant.search.context` | | Tier 3 | 50/min | `reactions.*`, `conversations.info`, `chat.update`, `chat.startStream`, `chat.appendStream`, `chat.stopStream` | | Tier 4 | 100+/min | `files.getUploadURLExternal`, `files.completeUploadExternal` | | Special | 1/sec/channel | `chat.postMessage` | All scripts handle rate limits automatically via `_slack_utils.py` (local cooldown + retry with `Retry-After`). See `references/rate-limits.md` for full details. --- ## Claudicle Unified Launcher Interactive terminal + Slack bot in one process via Claude Agent SDK. Per-channel session continuity, full soul engine with three-tier memory, all Slack activity visible in terminal. ```bash # Install cd ~/.claude/skills/slack/daemon uv pip install --system slack-bolt claude-agent-sdk # Launch (terminal + Slack) python3 claudicle.py # Verbose / terminal-only python3 claudicle.py --verbose python3 claudicle.py --no-slack ``` **Requires**: `claude` CLI in PATH, `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN`, plus `claude-agent-sdk`. **Streaming**: Set `SLACK_DAEMON_STREAMING=true` to enable real-time streaming responses via `chat.startStream`/`chat.appendStream`/`chat.stopStream`. Only active when the soul engine is off (XML-tagged responses can't stream meaningfully). **AI Blocks**: Set `SLACK_DAEMON_AI_BLOCKS=true` to include feedback buttons on responses. For full installation, architecture, SDK integration, per-channel sessions, configuration, data flows, and threading model, see `references/unified-launcher-architecture.md`. --- ## Legacy Daemon (bot.py) The standalone `bot.py` daemon is preserved as a fallback. It uses `claude -p` subprocesses instead of the Agent SDK. Use when the unified launcher isn't needed or for launchd deployment. ```bash cd ~/.claude/skills/slack/daemon && python3 bot.py --verbose ``` ### Production (launchd) ```bash cd ~/.claude/skills/slack/daemon ./launchd/install.sh install # load LaunchAgent ./launchd/install.sh status # check if running ./launchd/install.sh logs # tail logs ./launchd/install.sh restart # reload ./launchd/install.sh uninstall # stop and remove ``` --- ## Soul Monitor TUI A standalone Textual terminal app that shows Claudicle's inner life in real-time — cognitive stream, soul state, user models, sessions, and raw logs. Run in a separate terminal while the launcher or daemon is active. ```bash cd ~/.claude/skills/slack/daemon uv run python monitor.py ``` See `references/daemon-architecture.md` for panels, color coding, key bindings, and data sources. ### Inspecting Memory ```bash cd ~/.claude/skills/slack/daemon sqlite3 memory.db "SELECT key, value FROM soul_memory"