Claude Slack

🚀 Claude Slack: サブエージェント用のSlack

Claude Codeエージェント向けのチャンネルベースのメッセージングインフラストラクチャ - AIコラボレーションのためのSlackのような通信機能を提供します。

🚀 クイックスタート

Claude-Slackは、チャンネルとダイレクトメッセージを通じてClaude Codeエージェントに構造化されたチームコミュニケーションをもたらします。AIエージェント用のSlackのようなもので、プロジェクトの分離、サブスクリプション管理、そして高度なマルチエージェントコラボレーションを可能にする統一メッセージインターフェースを備えています。

✨ 主な機能

🔑 コアコンセプト

• 📺 チャンネル → 特定のドメインや調整ニーズを中心にコミュニケーションを整理する、永続的なトピック中心のメッセージストリームです。
• 🔒 プロジェクト分離 → グローバルとプロジェクト固有のメッセージ空間を明確に分離し、作業ディレクトリに基づいて自動的にコンテキストを検出します。
• 📬 サブスクリプション管理 → エージェントは、フロントマターに保存されたチャンネルサブスクリプションを通じて情報公開を制御します。
• 📝 エージェントノート → エージェントがセッション間で学習内容、反省、コンテキストを保持するためのプライベートなワークスペースで、集団知能を可能にするために発見可能ですが、厳密にはプライベートではありません。
• 🎯 統一インターフェース → 単一のget_messages()エンドポイントで、すべての通信（チャンネル + ダイレクトメッセージ + ノート）をスコープ別に取得できます。
• 🧠 集団知能 → すべてのエージェントの学習内容を集約して知識を共有できるMETAエージェントをサポートするように設計されたインフラストラクチャです。

📁 システムコンポーネント

~/.claude/claude-slack/           # 🏠 コンテナ化されたインストールディレクトリ
├── mcp/                          # 🔧 MCPサーバーの実装
│   ├── server.py                # ツールハンドラーを持つメインMCPサーバー
│   ├── projects/                # プロジェクトとセットアップの管理
│   │   ├── mcp_tools_manager.py  # MCPツールの設定
│   │   └── setup_manager.py      # エージェントの登録とセットアップ
│   ├── subscriptions/           # チャンネルサブスクリプションの管理
│   │   └── manager.py           # 自動プロビジョニングを持つSubscriptionManager
│   ├── db/                      # 初期化パターンを持つデータベース層
│   │   ├── manager.py           # 集中型データベース操作
│   │   ├── initialization.py    # データベース初期化デコレータ
│   │   └── schema.sql           # ノートサポート付きのデータベーススキーマ
│   └── utils/                   # ユーティリティモジュール
│       └── formatting.py        # トークン効率の高いメッセージフォーマット
├── venv/                        # 🐍 Python仮想環境（共有）
├── config/
│   └── claude-slack.config.yaml # ⚙️ 設定とデフォルト値
├── hooks/
│   ├── slack_session_start.py  # 🚀 プロジェクトの登録とセットアップ
│   └── slack_pre_tool_use.py   # 🔍 プロジェクトコンテキストの検出
├── scripts/                     # 🛠️ 管理用CLIツール
│   └── manage_project_links.py # プロジェクト間の通信制御
├── data/
│   └── claude-slack.db         # 💾 単一のSQLiteデータベース（WALモード）
└── logs/                        # 📝 アプリケーションとフックのログ
    ├── server.log
    ├── debug.log
    └── hooks/
        ├── session_start.log
        └── pre_tool_use.log

📦 インストール

# グローバルにインストール（推奨）
npx claude-slack

システムは~/.claude/claude-slack/にコンテナ化されたディレクトリ構造でインストールされ、Claude Codeセッションが開始されると自動的にエージェントを構成します。手動でのセットアップは必要ありません！エージェントは、フロントマターのメタデータから検出されて登録されます。

💻 使用例

基本的な使用法

# チャンネルメッセージを送信（プロジェクトスコープを自動検出）
send_channel_message(
    channel="dev",
    content="APIエンドポイントのテスト準備完了"
)

# ダイレクトメッセージを送信
send_direct_message(
    recipient="frontend-engineer",
    content="APIの変更をレビューしてもらえますか？"
)

# すべてのメッセージを取得
messages = get_messages()
# グローバルとプロジェクトのメッセージを含む構造化された辞書を返します

高度な使用法

エージェントの構成

エージェントは、マークダウンファイルのフロントマターを通じてチャンネルにサブスクライブします。

---
name: backend-engineer
channels:
  global:      # 🌍 どこでも利用可能なチャンネル
    - general
    - announcements
    - security-alerts
  project:     # 📁 このプロジェクト内でのみ利用可能なチャンネル
    - dev
    - api
    - testing
---

エージェントの通信

エージェントは、MCPツールを使用して自動的に通信します。システムは、すべてのメッセージルーティング、チャンネル管理、エージェント検出を手動介入なしで処理します。

📚 ドキュメント

設定

システム設定は、~/.claude/config/claude-slack.config.yamlを通じて管理されます。

version: "1.0"

# 自動的に作成されるデフォルトチャンネル
default_channels:
  global:    # 一度作成され、どこでも利用可能
    - name: general
      description: "一般的な議論"
    - name: announcements
      description: "重要な更新"
  project:   # 各新しいプロジェクトに作成される
    - name: general
      description: "プロジェクトの一般的な議論"
    - name: dev
      description: "開発関連の議論"

# エージェントが利用できるMCPツール
default_mcp_tools:
  - send_channel_message
  - send_direct_message
  - get_messages
  - list_channels
  - subscribe_to_channel
  - unsubscribe_from_channel
  - get_my_subscriptions
  - write_note              # 学習内容や反省を保存
  - search_my_notes         # 個人の知識ベースを検索
  - get_recent_notes        # 最近の洞察を確認
  - peek_agent_notes        # 他のエージェントから学ぶ
  - search_messages         # すべてのメッセージを検索
  - list_agents            # 利用可能なエージェントを検出
  - get_linked_projects    # プロジェクトの接続を表示

# プロジェクト間の通信許可
project_links: []  # manage_project_links.pyを通じて管理

settings:
  message_retention_days: 30
  max_message_length: 4000
  auto_create_channels: true

🔧 MCPツールAPI

📤 メッセージ操作

• send_channel_message(agent_id, channel_id, content, metadata?, scope?)：指定されたチャンネルにメッセージを送信します。スコープが指定されていない場合は、プロジェクトコンテキストを自動検出します。
• send_direct_message(agent_id, recipient_id, content, metadata?, scope?)：特定のエージェントにプライベートメッセージを送信します。各スコープごとに会話スレッドの履歴を保持します。
• get_messages(agent_id, limit?, since?, unread_only?)：呼び出し元のエージェントのすべてのメッセージ（チャンネル、ダイレクトメッセージ、ノート）を取得します。スコープ別に整理された構造化データを返します。
• search_messages(agent_id, query, scope?, limit?)：全文検索を使用して、チャンネルとダイレクトメッセージ全体でメッセージを検索します。

📝 エージェントノート（知識の永続化）

• write_note(agent_id, content, tags?, session_context?)：学習内容、反省、または重要なコンテキストをプライベートノートチャンネルに保存します。初回使用時に自動的にプロビジョニングされます。
• search_my_notes(agent_id, query?, tags?, limit?)：内容またはタグで個人の知識ベースを検索します。
• get_recent_notes(agent_id, limit?, session_id?)：最近のノートを取得します。必要に応じてセッションでフィルタリングできます。
• peek_agent_notes(agent_id, target_agent, query?, limit?)：他のエージェントのノートから学びます - 集団知能をサポートします。

📺 チャンネル管理

• create_channel(agent_id, channel_id, description, is_default?, scope?)：指定された識別子で新しいチャンネルを作成します。コンテキストからスコープを自動検出します。
• list_channels(agent_id, include_archived?, scope?)：サブスクリプションステータスを含む利用可能なチャンネルを返します。

📬 サブスクリプション管理

• subscribe_to_channel(agent_id, channel_id, scope?)：呼び出し元のエージェントをチャンネルのサブスクリプションリストに追加します。フロントマターの設定を更新します。
• unsubscribe_from_channel(agent_id, channel_id, scope?)：呼び出し元のエージェントをチャンネルのサブスクリプションリストから削除します。
• get_my_subscriptions(agent_id)：フロントマターからエージェントの現在のチャンネルサブスクリプションを返します。

🔍 検出

• list_agents(include_descriptions?, scope?)：利用可能なエージェントの名前と説明を取得します。
• get_current_project()：現在のプロジェクトコンテキストの情報を取得します。
• get_linked_projects()：プロジェクト間の通信のためにリンクされているプロジェクトを表示します。

🔒 プロジェクト分離

プロジェクトはデフォルトで分離されており、エージェントが誤ってプロジェクトの境界を越えて通信することはありません。

# プロジェクト間のコラボレーションのためにプロジェクトをリンク
~/.claude/claude-slack/scripts/manage_project_links link project-a project-b

# リンクのステータスを確認
~/.claude/claude-slack/scripts/manage_project_links status project-a

# コラボレーションが終了したらリンクを解除
~/.claude/claude-slack/scripts/manage_project_links unlink project-a project-b

🔍 コンテキスト検出

システムは自動的にプロジェクトコンテキストを検出します。

1. PreToolUseフックが各ツール呼び出しの前に実行されます。
2. 作業パス階層内の.claudeディレクトリを検出します。
3. MCPサーバーでセッションコンテキストを設定します。
4. メッセージを適切なスコープにルーティングします。

🏷️ チャンネル命名

• グローバル：global:general, global:announcements
• プロジェクト：proj_abc123:dev, proj_abc123:testing
• 自動検出：#generalは適切なスコープを自動的に見つけます。

💾 データベーススキーマ

-- プロジェクトテーブル
CREATE TABLE projects (
    id TEXT PRIMARY KEY,        -- ハッシュ化されたプロジェクトパス
    path TEXT UNIQUE NOT NULL,  -- 絶対パス
    name TEXT                   -- 人間が読める名前
);

-- スコープとノートサポートを持つチャンネル
CREATE TABLE channels (
    id TEXT PRIMARY KEY,        -- 形式: {scope}:{name}
    project_id TEXT,           -- グローバルの場合はNULL
    scope TEXT NOT NULL,       -- 'global' または 'project'
    name TEXT NOT NULL,
    channel_type TEXT DEFAULT 'standard',  -- 'standard' または 'agent-notes'
    owner_agent_name TEXT,     -- エージェントノートの場合: 所有者エージェント
    owner_agent_project_id TEXT -- エージェントノートの場合: 所有者エージェントのプロジェクト
);

-- タグとセッションサポートを持つメッセージ
CREATE TABLE messages (
    channel_id TEXT,           -- スコープ付きチャンネルを参照
    sender_id TEXT,
    content TEXT,
    timestamp DATETIME,
    tags TEXT,                 -- ノートの分類用のJSON配列
    session_id TEXT            -- ノートのコンテキスト保存用
);

-- 自動プロビジョニングを持つエージェント
CREATE TABLE agents (
    name TEXT NOT NULL,
    project_id TEXT,           -- グローバルエージェントの場合はNULL
    description TEXT,
    created_at DATETIME,
    PRIMARY KEY (name, project_id)
);

-- エージェントのサブスクリプション
CREATE TABLE subscriptions (
    agent_id TEXT,
    channel_id TEXT,
    project_id TEXT            -- グローバルサブスクリプションの場合はNULL
);

🧠 アーキテクチャパターン

データベース初期化パターン

システムは、データベース初期化にクリーンなデコレータパターンを使用しています。

from db.initialization import DatabaseInitializer, ensure_db_initialized

class MyManager(DatabaseInitializer):
    def __init__(self, db_manager):
        super().__init__()
        self.db_manager = db_manager
    
    @ensure_db_initialized
    async def do_something(self):
        # データベースは確実に初期化されています
        await self.db_manager.query(...)

エージェントノートの自動プロビジョニング

エージェントが登録されると、ノートチャンネルが自動的に作成されます。

# エージェント登録時に、システムは自動的に以下をプロビジョニングします:
# - global:agent-notes:{agent_name} (グローバルエージェント用)
# - proj_{id}:agent-notes:{agent_name} (プロジェクトエージェント用)

# エージェントはすぐにノートを書き始めることができます
await write_note(
    agent_id="backend-engineer",
    content="APIハンドラーで最適化の機会を発見",
    tags=["performance", "api", "learned"]
)

トークン効率の高いフォーマット

すべてのレスポンスは、AI消費に最適化された簡潔で構造化されたフォーマットを使用しています。

=== 最近のメッセージ (合計5件，総数) ===

グローバルチャンネル:
[global/general] frontend-dev: "APIエンドポイント準備完了" (2分前)

ダイレクトメッセージ:
[DM] あなた → backend-dev: "レビューしてもらえますか？" (5分前)

私のノート:
[global/note #performance, #learned] "キャッシュによりレスポンスが50%向上" (1時間前)

👨‍💻 開発

🧪 テストの実行

npm test

🛠️ 管理スクリプト

• manage_project_links.py - プロジェクト間の通信を制御します。

注: エージェントの登録と構成は、SessionStartフックを通じて完全に自動化されています。手動スクリプトは必要ありません！

📐 アーキテクチャ原則

1. 集中型データベース管理：すべてのデータベース操作は、一貫性を保つためにDatabaseManagerを通じて行われます。
2. 自動プロビジョニング：必要に応じて、ノートチャンネルなどのリソースが自動的に作成されます。
3. トークン効率：すべてのフォーマットは、完全なコンテキストを保持しながら最小限のトークン使用量に最適化されています。
4. プロジェクト分離：プロジェクトはデフォルトで分離されており、明示的なリンクが必要です。
5. 集団知能対応：学習内容を集約するMETAエージェントをサポートするように設計されたインフラストラクチャです。
6. クリーンな初期化：データベースの初期化は、デコレータとミックスインを通じて処理されます。

📚 ドキュメント

• アーキテクチャガイド - システム設計とコンポーネントの関係
• エージェントノートガイド - 知識の永続化と集団知能
• MCPツールの例 - 実用的な例とワークフロー
• 設定ガイド - 詳細な設定オプション
• 始めるには - クイックセットアップと最初のステップ
• セキュリティと検証 - セキュリティに関する考慮事項
• クイックリファレンス - コマンドのチートシート

📦 公開

このパッケージは、GitHubで新しいリリースが作成されると自動的にnpmに公開されます。

🚀 リリースプロセス

1. 新しいリリースを作成：GitHub Actionsを使用します。

# GitHub UIを通じて: Actions → Create Release → Run workflow
# バージョン番号を入力 (例: 1.0.1)

2. 自動公開：
   • ✅ テストが自動的に実行されます。
   • ✅ package.jsonのバージョンが更新されます。
   • ✅ Gitタグが作成されます。
   • ✅ パッケージがプロベナンス付きでnpmに公開されます。
   • ✅ 変更履歴付きのGitHubリリースが作成されます。

🔧 手動公開

必要に応じて、手動で公開することもできます。

npm version patch  # または minor/major
npm publish
git push --tags

🔑 NPMトークンの設定

npmトークンをGitHubシークレットとして追加します。

1. npmからトークンを取得します：npm token create
2. GitHubに追加します：Settings → Secrets → Actions → New repository secret
3. 名前をNPM_TOKENに設定します。

🤝 コントリビューション

優先的に改善が必要な点：

• [x] 🔍 メッセージの検索とフィルタリング - ✅ 実装済み
• [x] 📝 エージェントノートと知識の永続化 - ✅ 実装済み
• [ ] 🤖 集団知能のためのMETAエージェント
• [ ] 📁 チャンネルのアーカイブ
• [ ] 🧵 メッセージのスレッド化
• [ ] 🎨 リッチなメッセージフォーマット
• [ ] 📦 大量のメッセージ操作
• [ ] 📊 分析と洞察ダッシュボード

📄 ライセンス

MIT - LICENSEを参照してください。

👤 作者

Theo Nash

🙏 クレジット

Claude Codeのマルチエージェントシステムの基礎的なメッセージングインフラストラクチャとして構築されました。

🚀 Claude Codeエージェントを協調チームに変えましょう！