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.

# 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 → 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):

   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

# 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.

# 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.

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:

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.

# 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.

cd ~/.claude/skills/slack/daemon && python3 bot.py --verbose

Production (launchd)

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.

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