Slack Skill

Slack workspace integration with two components:

Scripts — 7 Python scripts for on-demand Slack operations (bundled here)
Session Bridge — connect THIS Claude Code session to Slack (background listener + inbox file, no extra API costs)

Daemon & Soul Engine: The Claudicle daemon (unified launcher, soul engine, cognitive pipeline, three-tier memory, Soul Monitor TUI) now lives in its own repo: github.com/tdimino/claudicle. Install Claudicle separately for daemon features.

When to Use This Skill

Scripts (on-demand)

Posting messages to Slack channels or threads
Reading channel history or thread replies
Searching messages or files across the workspace
Adding or managing reactions on messages
Uploading files or code snippets
Listing channels, getting channel info, or joining channels
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)

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

# Verify token is set
echo $SLACK_BOT_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:read
- channels:history, groups:history, im:history, mpim:history
- channels:read, groups:read, im:read, im:write
- chat:write
- files:write, files:read
- reactions:write, reactions:read
- search:read
- users:read, users:read.email
- users: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 @mentions
- message.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):

export SLACK_BOT_TOKEN=xoxb-...   # Bot User OAuth Token
export SLACK_APP_TOKEN=xapp-...   # App-Level Token (Socket Mode)

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

Quick Start

# Post a message
python3 ~/.claude/skills/slack/scripts/slack_post.py "#general" "Hello from Claude"

# Read recent messages
python3 ~/.claude/skills/slack/scripts/slack_read.py "#general" -n 10

# Search the workspace
python3 ~/.claude/skills/slack/scripts/slack_search.py "deployment status"

# Connect this session to Slack via Claudicle Session Bridge
# (requires Claudicle installed — see github.com/tdimino/claudicle)
cd ~/.claudicle/daemon && python3 slack_listen.py --bg
python3 ~/.claude/skills/slack/scripts/slack_check.py

Session Bridge

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.

Requires Claudicle daemon installed — see github.com/tdimino/claudicle.

# Connect
cd ~/.claudicle/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
cd ~/.claudicle/daemon && python3 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.

For full installation, architecture, inbox format, auto-notification hook, and troubleshooting, see references/session-bridge.md.

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 messages	`slack_search.py`	`slack_search.py "query"`
Search files	`slack_search.py`	`slack_search.py "query" --files`
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"`
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`
Tier 3	50/min	`reactions.*`, `conversations.info`, `chat.update`
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.

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	Invite bot to channels with `/invite @Claude Code`, or use user token (`xoxp-`)
Rate limited (429)	Scripts auto-retry; reduce batch sizes
"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

For daemon-specific troubleshooting (soul engine, memory, launcher), see Claudicle docs.

File Structure

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_search.py      # Search messages or files
├── slack_react.py       # Add/remove reactions
├── slack_upload.py      # Upload files or snippets
├── 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 7 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