| name | slack |
| description | Slack workspace integration: 9 on-demand scripts (post, read, delete, search, stream, react, upload, channels, users) + dual-token support + RTS API search + chat streaming + AI Block Kit + Session Bridge + Claudicle unified launcher (Claude Agent SDK, soul engine, three-tier memory). |
Slack Skill
Full Slack workspace integration with three modes:
- Scripts — 9 Python scripts for on-demand Slack operations
- Session Bridge — connect THIS Claude Code session to Slack (background listener + inbox file, no extra API costs)
- 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.
echo $SLACK_BOT_TOKEN
echo $SLACK_USER_TOKEN
First-Time Setup
- Go to api.slack.com/apps → Create New App → From Scratch
- Name it "Claude Code" → select your workspace
- OAuth & Permissions → Bot Token Scopes → add all:
app_mentions:readchannels:history, groups:history, im:history, mpim:historychannels:read, groups:read, im:read, im:writechannels:join — enables bot to join public channels programmaticallychat:writefiles:write, files:readreactions:write, reactions:readsearch: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.emailusers:write (optional — enables green presence dot)
- Settings → Socket Mode → toggle ON → generate an App-Level Token:
- Name:
socket-mode
- Scope:
connections:write
- Copy the
xapp- token
- Event Subscriptions → toggle ON (no Request URL needed with Socket Mode) → Subscribe to Bot Events → add:
app_mention — channel @mentionsmessage.im — direct messages (required for DMs to work)app_home_opened — App Home tab rendering
- App Home → Show Tabs → enable "Allow users to send Slash commands and messages from the messages tab"
- Install to Workspace → approve permissions → copy Bot User OAuth Token
- Set environment variables (add to shell profile):
After any scope or event subscription change: reinstall the app (Install App → Reinstall to Workspace) and restart the launcher.
Quick Start
python3 ~/.claude/skills/slack/scripts/slack_post.py "#general" "Hello from Claude"
python3 ~/.claude/skills/slack/scripts/slack_post.py "#general" "Here's my analysis" --ai
python3 ~/.claude/skills/slack/scripts/slack_read.py "#general" -n 10
python3 ~/.claude/skills/slack/scripts/slack_search.py "deployment status"
python3 ~/.claude/skills/slack/scripts/slack_search.py "deployment" --rts --type channels
python3 ~/.claude/skills/slack/scripts/slack_stream.py "#general" "Streaming message..."
python3 ~/.claude/skills/slack/scripts/slack_channels.py --join-all-public
cd ~/.claude/skills/slack/daemon && python3 slack_listen.py --bg
python3 ~/.claude/skills/slack/scripts/slack_check.py
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.
cd ~/.claude/skills/slack/daemon && python3 slack_listen.py --bg
python3 ~/.claude/skills/slack/scripts/slack_check.py
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
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.
python3 slack_format.py perception "Tom" "What's the status?"
echo "$raw" | python3 slack_format.py extract
echo "$raw" | python3 slack_format.py extract --narrate --log
python3 slack_format.py instructions
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:
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
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 |
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.
cd ~/.claude/skills/slack/daemon
uv pip install --system slack-bolt claude-agent-sdk
python3 claudicle.py
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.
cd ~/.claude/skills/slack/daemon && python3 bot.py --verbose
Production (launchd)
cd ~/.claude/skills/slack/daemon
./launchd/install.sh install
./launchd/install.sh status
./launchd/install.sh logs
./launchd/install.sh restart
./launchd/install.sh uninstall
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.
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
cd ~/.claude/skills/slack/daemon
sqlite3 memory.db "SELECT key, value FROM soul_memory"
sqlite3 memory.db "SELECT user_id, display_name, interaction_count FROM user_models"
sqlite3 memory.db "SELECT entry_type, verb, content FROM working_memory ORDER BY created_at DESC LIMIT 20"
sqlite3 sessions.db "SELECT channel, thread_ts, session_id FROM sessions"
New User Onboarding
Bootstrap personalized configuration by having Claudicle interview new users to build user models and generate CLAUDE.md files. See references/onboarding-guide.md for the full workflow.
Troubleshooting
| Problem | Fix |
|---|
| Bot not responding to @mentions | Enable Socket Mode; verify SLACK_APP_TOKEN (xapp-) is exported |
| "missing_scope" error | Add the missing scope in OAuth & Permissions → reinstall app |
| No search results | Add search:read.* scopes for RTS API, or invite bot to channels, or set SLACK_USER_TOKEN for legacy search |
| RTS search "missing_scope" | Add granular search:read.* scopes → reinstall app; script auto-falls back to legacy |
| Streaming not working | Set SLACK_DAEMON_STREAMING=true; streaming is disabled when soul engine is on |
channels:join denied | Add channels:join scope → reinstall app |
| Rate limited (429) | Scripts auto-retry; reduce batch sizes |
| Launcher/daemon exits immediately | Verify which claude returns a path |
| "Credit balance is too low" | Check Anthropic billing; error now surfaces in Slack response |
| Soul engine XML parsing fails | Check daemon/logs/claudicle.log; fallback raw text is returned |
| "Sending messages turned off" | App Home → enable "Allow users to send Slash commands and messages from the messages tab" |
| No green presence dot | Add users:write scope → reinstall app |
| App Home tab blank | Subscribe to app_home_opened event |
| Monitor TUI won't start | cd daemon && uv pip install textual psutil |
| SDK import error | uv pip install --system claude-agent-sdk |
File Structure
daemon/
├── slack_listen.py # Session Bridge: background Socket Mode listener
├── inbox.jsonl # Session Bridge: incoming messages (auto-created)
├── claudicle.py # Unified launcher (terminal + Slack, requires SDK)
├── slack_adapter.py # Socket Mode event handling (extracted from bot.py)
├── terminal_ui.py # Async terminal input + activity log
├── claude_handler.py # Claude invocation (subprocess + SDK async)
├── soul_engine.py # Cognitive prompt wrapping + XML parsing
├── working_memory.py # Per-thread metadata store
├── user_models.py # Per-user personality profiles
├── soul_memory.py # Global soul state
├── session_store.py # Thread → session ID mapping
├── config.py # All settings (env var overrides)
├── bot.py # Legacy standalone daemon (fallback)
├── monitor.py # Soul Monitor TUI (Textual)
├── watcher.py # DB file watcher for monitor
├── soul.md # Claudicle personality blueprint
├── skills.md # Capabilities reference
├── launchd/ # macOS LaunchAgent scripts
├── logs/ # Runtime logs
├── memory.db # SQLite: soul_memory, user_models, working_memory
└── sessions.db # SQLite: session_id mappings
scripts/
├── slack_check.py # Session Bridge: read/ack inbox messages
├── slack_inbox_hook.py # Session Bridge: UserPromptSubmit auto-check hook
├── slack_format.py # Soul formatter: perception/extract/instructions (Open Souls paradigm)
├── slack_post.py # Post messages to channels/threads
├── slack_read.py # Read channel history or threads
├── slack_delete.py # Delete messages (single, batch, thread cleanup)
├── slack_search.py # Search messages, files, channels, users (RTS + legacy)
├── slack_stream.py # Stream messages in real-time via chat streaming API
├── slack_react.py # Add/remove reactions
├── slack_upload.py # Upload files or snippets
├── slack_memory.py # CLI wrapper for three-tier memory system
├── slack_app_home.py # Build + publish App Home tab via Block Kit
├── slack_channels.py # List/join channels
├── slack_users.py # Look up users
└── _slack_utils.py # Shared auth, rate limiting, API calls
Reference Index
| Reference | Contents |
|---|
references/session-bridge.md | Session Bridge: installation, architecture, inbox format, usage workflow, soul formatter, troubleshooting |
references/unified-launcher-architecture.md | Unified launcher: installation, architecture, per-channel sessions, SDK integration, data flows, threading model |
references/daemon-architecture.md | Soul engine cognitive steps, memory tiers, XML format, App Home, Soul Monitor TUI |
references/scripts-reference.md | Full documentation for all 8 scripts, test suite, common workflows |
references/onboarding-guide.md | User model interview, CLAUDE.md generation, export commands |
references/rate-limits.md | Slack API rate limit tiers and handling strategy |
Assets
assets/app-icon.png — Slack app icon for bot configuration
