slack

Slack スキル

3 つのモードで Slack ワークスペースと完全に連携します：

1. スクリプト — 必要に応じて Slack 操作を行う 9 個の Python スクリプト
2. セッションブリッジ — この Claude Code セッションを Slack に接続します（バックグラウンドリスナー＋受信トレイファイル、追加の API コストなし）
3. 統合ランチャー — Claude Agent SDK、ソウルエンジン、チャンネルごとのセッションを備えた claudicle.py（SDK API キーが必要）

このスキルを使用する場面

スクリプト（必要に応じて実行）

• Slack チャンネルやスレッドへのメッセージ投稿（任意で AI フィードバックボタンを追加）
• チャンネル履歴やスレッドの返信を読む
• RTS API（利用できない場合は旧方式にフォールバック）でメッセージ、ファイル、チャンネル、ユーザーを検索
• チャットストリーミング API でメッセージをリアルタイムにストリーミング
• メッセージへのリアクションの追加や管理
• ファイルやコードスニペットのアップロード
• チャンネル一覧の取得、チャンネル情報の取得、チャンネルへの参加（一括参加を含む）
• 名前、ID、メールアドレスでユーザーを検索

セッションブリッジ（推奨）

• 実行中の任意の Claude Code セッションを Slack に接続
• すべてのツールにアクセスして @メンションや DM に返信（このセッション自体が頭脳です）
• 追加の API コストなし — メッセージは現在のセッションコンテキストで処理
• UserPromptSubmit フックによる新着メッセージの自動通知
• soul.md の指示に従って Claudicle として振る舞う（XML の仕組みは不要）

統合ランチャー（常時稼働、SDK API キーが必要）

• Claudicle をインタラクティブなターミナルと Slack ボットとして 1 つのプロセスで実行
• 「Claudicle, Artifex Maximus」として @メンションや DM にリアルタイムで返信
• スレッドでの複数ターン会話（Claude Agent SDK によるチャンネルごとのセッション継続）
• ユーザーごとのパーソナリティモデリング（コミュニケーションスタイル、関心、専門知識を学習）
• スレッドをまたいだソウル状態（現在のプロジェクト、タスク、トピック、感情の状態を追跡）
• 3 層のメモリ：作業メモリ（スレッドごと）、ユーザーモデル（ユーザーごと）、ソウルメモリ（全体）
• ターミナルとの直接的なやり取りと並行して、すべての Slack アクティビティをターミナルに表示

前提条件

すべてのスクリプトには、環境変数 SLACK_BOT_TOKEN（xoxb- で始まる Bot User OAuth Token）が必要です。また、スクリプトには requests も必要です（uv pip install --system requests）。

任意：SLACK_USER_TOKEN（xoxp-）を設定すると、RTS API が利用できない場合に旧方式の search.messages／search.files でワークスペース全体を検索できます。その他すべての操作にはボットトークンが使用されます。

# Verify tokens
echo $SLACK_BOT_TOKEN
echo $SLACK_USER_TOKEN  # optional, for legacy search fallback

初回セットアップ

1. api.slack.com/apps に移動 → Create New App → From Scratch
2. 名前に「Claude Code」を指定 → ワークスペースを選択
3. OAuth & Permissions → Bot Token Scopes → すべて追加します：
   • app_mentions:read
   • channels:history, groups:history, im:history, mpim:history
   • channels:read, groups:read, im:read, im:write
   • channels:join — ボットがプログラムからパブリックチャンネルに参加できるようにします
   • chat:write
   • files:write, files:read
   • reactions:write, reactions:read
   • search:read — 従来の検索（ボットから見えるチャンネルのみ）
   • search:read.public, search:read.private, search:read.im, search:read.mpim, search:read.files, search:read.users — RTS API（統合検索、2026年2月以降）
   • users:read, users:read.email
   • users:write（任意 — 緑色のプレゼンスドットを有効にします）
4. Settings → Socket Mode → ON に切り替え → App-Level Token を生成します：
   • 名前：socket-mode
   • スコープ：connections:write
   • xapp- トークンをコピーします
5. Event Subscriptions → ON に切り替えます（Socket Mode では Request URL は不要です）→ Subscribe to Bot Events → 次を追加します：
   • app_mention — チャンネルでの @メンション
   • message.im — ダイレクトメッセージ（DM を機能させるために必要です）
   • app_home_opened — App Home タブの表示
6. App Home → Show Tabs → 「Allow users to send Slash commands and messages from the messages tab」 を有効にします
7. Install to Workspace → 権限を承認 → Bot User OAuth Token をコピーします
8. 環境変数を設定します（シェルのプロファイルに追加）：

   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 @Claude Code

スコープまたはイベントサブスクリプションを変更した場合：アプリを再インストール（Install App → Reinstall to Workspace）し、ランチャーを再起動します。

---

クイックスタート

# 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

---

セッションブリッジ（推奨）

実行中の任意の Claude Code セッションを Slack に接続します。バックグラウンドリスナーが @メンションと DM を検知し、inbox.jsonl に書き込みます。このセッションは受信トレイを読み込み、すべてのツールにアクセスして処理し、応答を Slack に投稿します。追加の API コストはかかりません。

# 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（任意）：scripts/slack_format.py は Open Souls の認知ステップ形式を追加します。知覚のフレーミング、対話の抽出、モノローグの記録に対応します。

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

自動応答：/slack-respond は、保留中のすべてのメッセージを Claudicle として、知覚、モノローグ、対話、投稿、確認という認知ステップをすべて実行して処理します。1 回の呼び出しで完了します。~/.claude/skills/slack-respond/SKILL.md を参照してください。

Soul Activation：/ensoul は、圧縮や再開を経ても soul.md を継続的に注入し、任意の Claude Code セッションで Claudicle のアイデンティティを有効にします。続けて /slack-sync #channel を実行すると、魂を有効にしたセッションを Slack チャンネルに紐付けます。どちらもセッションごとに任意で有効化できます。ソウルレジストリ（~/.claude/hooks/soul-registry.py）は、魂が有効かどうかにかかわらず、すべてのアクティブなセッションとそのチャンネルの紐付けを追跡します。

インストール、アーキテクチャ、受信トレイの形式、自動通知フック、トラブルシューティングの詳細については、references/session-bridge.md を参照してください。

App Home：ユーザーが Claudicle のプロフィールを開くと、リスナーの app_home_opened によって Home タブが自動的に表示されます。ライブステータス、ツールキット、認知アーキテクチャ、メモリーシステムを表示します。手動で更新するには：

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

---

スクリプト選択ガイド

タスク	スクリプト	例
メッセージを投稿する	slack_post.py	slack_post.py "#general" "Hello"
スレッドに返信する	slack_post.py	slack_post.py "#ch" "reply" --thread TS
メッセージを予約する	slack_post.py	slack_post.py "#ch" "msg" --schedule ISO
チャンネルの履歴を読む	slack_read.py	slack_read.py "#general" -n 20
スレッドを読む	slack_read.py	slack_read.py "#ch" --thread TS
検索する（RTS、自動）	slack_search.py	slack_search.py "query"
メッセージのみを検索する	slack_search.py	slack_search.py "query" --type messages
ファイルを検索する	slack_search.py	slack_search.py "query" --files
チャンネル／ユーザーを検索する	slack_search.py	slack_search.py "query" --rts --type channels
メッセージをストリーミングする	slack_stream.py	slack_stream.py "#ch" "text" --chunk-size 50
標準入力からストリーミングする	slack_stream.py	echo "text" | slack_stream.py "#ch" --stdin
AI ボタン付きで投稿する	slack_post.py	slack_post.py "#ch" "msg" --ai
メッセージを削除する	slack_delete.py	slack_delete.py "#ch" TS1 TS2
スレッドをクリーンアップする（ボットのメッセージ）	slack_delete.py	slack_delete.py "#ch" --thread TS
リアクションを追加する	slack_react.py	slack_react.py "#ch" TS emoji
ファイルをアップロードする	slack_upload.py	slack_upload.py "#ch" ./file.pdf
コードスニペットを共有する	slack_upload.py	slack_upload.py "#ch" --snippet CODE
チャンネルを一覧表示する	slack_channels.py	slack_channels.py
チャンネルに参加する	slack_channels.py	slack_channels.py --join "#ch"
すべての公開チャンネルに参加する	slack_channels.py	slack_channels.py --join-all-public
メールアドレスでユーザーを検索する	slack_users.py	slack_users.py --email [email protected]

スクリプトの全ドキュメント（すべてのパラメーター、例、テストスイート、一般的なワークフロー）については、references/scripts-reference.md を参照してください。

---

レート制限への注意

ティア	レート	主要なメソッド
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
特別	1/sec/channel	chat.postMessage

すべてのスクリプトは、_slack_utils.py を通じてレート制限を自動的に処理します（ローカルのクールダウンと Retry-After による再試行）。詳しくは references/rate-limits.md を参照してください。

---

Claudicle 統合ランチャー

Claude Agent SDK を介して、インタラクティブなターミナルと Slack ボットを1つのプロセスで実行します。チャンネルごとのセッション継続性、3層メモリを備えた完全なソウルエンジン、Slack のすべてのアクティビティをターミナルに表示します。

# 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

必要なもの：PATH 上の claude CLI、SLACK_BOT_TOKEN、SLACK_APP_TOKEN、および claude-agent-sdk。

ストリーミング：SLACK_DAEMON_STREAMING=true を設定すると、chat.startStream／chat.appendStream／chat.stopStream によるリアルタイムのストリーミング応答が有効になります。ソウルエンジンがオフの場合にのみ有効です（XML タグ付きの応答は意味のある形でストリーミングできません）。

AI ブロック：SLACK_DAEMON_AI_BLOCKS=true を設定すると、応答にフィードバックボタンが追加されます。

インストール、アーキテクチャ、SDK 統合、チャンネルごとのセッション、設定、データフロー、スレッドモデルについて詳しくは、references/unified-launcher-architecture.md を参照してください。

---

レガシーデーモン（bot.py）

スタンドアロンの bot.py デーモンは、フォールバックとして維持されています。Agent SDK の代わりに claude -p サブプロセスを使用します。統合ランチャーが不要な場合や、launchd でデプロイする場合に使用してください。

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

本番環境（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

Claudicle の内面をリアルタイムで表示する、Textual 製のスタンドアロン端末アプリです。認知ストリーム、魂の状態、ユーザーモデル、セッション、生ログを表示します。ランチャーまたはデーモンの実行中に、別の端末で起動してください。

cd ~/.claude/skills/slack/daemon
uv run python monitor.py

パネル、色分け、キー操作、データソースについては、references/daemon-architecture.md を参照してください。

メモリの確認

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"

---

新規ユーザーのオンボーディング

Claudicle が新規ユーザーにインタビューを行い、ユーザーモデルを作成して CLAUDE.md ファイルを生成することで、パーソナライズされた設定を初期化します。ワークフロー全体については、references/onboarding-guide.md を参照してください。

---

トラブルシューティング

問題	対処方法
ボットが @メンションに応答しない	Socket Mode を有効にします。SLACK_APP_TOKEN（xapp-）がエクスポートされていることを確認します
"missing_scope" エラー	OAuth & Permissions に不足しているスコープを追加し、アプリを再インストールします
検索結果が表示されない	RTS API 用の search:read.* スコープを追加するか、ボットをチャンネルに招待するか、従来の検索用に SLACK_USER_TOKEN を設定します
RTS 検索で "missing_scope" が発生する	詳細な search:read.* スコープを追加してアプリを再インストールします。スクリプトは自動的に従来の検索にフォールバックします
ストリーミングが機能しない	SLACK_DAEMON_STREAMING=true を設定します。魂エンジンがオンの場合、ストリーミングは無効になります
channels:join が拒否される	channels:join スコープを追加してアプリを再インストールします
レート制限（429）が発生する	スクリプトは自動的に再試行します。バッチサイズを小さくしてください
ランチャー／デーモンがすぐに終了する	which claude がパスを返すことを確認します
"Credit balance is too low"	Anthropic の請求状況を確認します。エラーは Slack の応答に表示されるようになりました
魂エンジンの XML 解析に失敗する	daemon/logs/claudicle.log を確認します。フォールバックとして生テキストが返されます
"Sending messages turned off"	App Home → "Allow users to send Slash commands and messages from the messages tab" を有効にします
緑色のプレゼンスドットが表示されない	users:write スコープを追加してアプリを再インストールします
App Home タブが空白になる	app_home_opened イベントをサブスクライブします
Monitor TUI が起動しない	cd daemon && uv pip install textual psutil
SDK のインポートエラー	uv pip install --system claude-agent-sdk

---

ファイル構成

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

---

リファレンス一覧

リファレンス	内容
references/session-bridge.md	Session Bridge：インストール、アーキテクチャ、受信トレイ形式、使用ワークフロー、魂フォーマッター、トラブルシューティング
references/unified-launcher-architecture.md	統合ランチャー：インストール、アーキテクチャ、チャンネルごとのセッション、SDK 統合、データフロー、スレッドモデル
references/daemon-architecture.md	魂エンジンの認知ステップ、メモリ階層、XML 形式、App Home、Soul Monitor TUI
references/scripts-reference.md	8 つすべてのスクリプト、テストスイート、一般的なワークフローの詳細なドキュメント
references/onboarding-guide.md	ユーザーモデルのインタビュー、CLAUDE.md の生成、エクスポートコマンド
references/rate-limits.md	Slack API のレート制限の階層と対処方針

アセット

• assets/app-icon.png — ボット設定用の Slack アプリアイコン