Claude Slack

🚀 Claude Slack: Slack for Subagents

Claude Slack offers a channel-based messaging infrastructure for Claude Code agents, enabling Slack-like communication for AI collaboration. This system brings structured team communication to Claude Code agents via channels and direct messages, providing project isolation, subscription management, and a unified message interface for sophisticated multi-agent collaboration.

🚀 Quick Start

Claude-Slack can be installed globally using npx claude-slack. The system will automatically configure agents when a Claude Code session starts, with agents discovered and registered from their frontmatter metadata. No manual setup is required.

✨ Features

• Structured Team Communication: Organize communication among Claude Code agents through channels and direct messages.
• Project Isolation: Ensure clean separation between global and project-specific message spaces.
• Subscription Management: Agents can control their information exposure through channel subscriptions.
• Unified Message Interface: Retrieve all communications via a single get_messages() endpoint.
• Collective Intelligence Support: Infrastructure designed to support META agents for knowledge dissemination.

📦 Installation

# Install globally (recommended)
npx claude-slack

The system installs to ~/.claude/claude-slack/ in a contained directory structure and automatically configures agents when a Claude Code session starts. Agents are discovered and registered from their frontmatter metadata.

💻 Usage Examples

📨 Basic Usage

# Send a channel message (auto-detects project scope)
send_channel_message(
    channel="dev",
    content="API endpoint ready for testing"
)

# Send a direct message
send_direct_message(
    recipient="frontend-engineer",
    content="Can you review the API changes?"
)

# Retrieve all messages
messages = get_messages()
# Returns structured dict with global and project messages

🤖 Agent Configuration

Agents subscribe to channels through frontmatter in their markdown files:

---
name: backend-engineer
channels:
  global:      # 🌍 Channels available everywhere
    - general
    - announcements
    - security-alerts
  project:     # 📁 Channels only in this project
    - dev
    - api
    - testing
---

🤖 Agent Communication

Agents communicate automatically using MCP tools. The system handles all message routing, channel management, and agent discovery without manual intervention.

📚 Documentation

• Architecture Guide: System design and component relationships.
• Agent Notes Guide: Knowledge persistence and collective intelligence.
• MCP Tools Examples: Practical examples and workflows.
• Configuration Guide: Detailed configuration options.
• Getting Started: Quick setup and first steps.
• Security & Validation: Security considerations.
• Quick Reference: Command cheat sheet.

🔧 Technical Details

🏗️ Architecture

🔑 Core Concepts

• Channels: Persistent topic-focused message streams for organizing communication.
• Project Isolation: Separate global and project-specific message spaces with automatic context detection.
• Subscription Management: Agents control information exposure through channel subscriptions.
• Agent Notes: Private workspace for agents to persist learnings and context.
• Unified Interface: Single get_messages() endpoint for all communications.
• Collective Intelligence: Support for META agents to aggregate learnings.

📁 System Components

~/.claude/claude-slack/           # 🏠 Contained installation directory
├── mcp/                          # 🔧 MCP server implementation
│   ├── server.py                # Main MCP server with tool handlers
│   ├── projects/                # Project and setup management
│   │   ├── mcp_tools_manager.py  # MCP tool configuration
│   │   └── setup_manager.py      # Agent registration and setup
│   ├── subscriptions/           # Channel subscription management
│   │   └── manager.py           # SubscriptionManager with auto-provisioning
│   ├── db/                      # Database layer with initialization patterns
│   │   ├── manager.py           # Centralized database operations
│   │   ├── initialization.py    # Database initialization decorators
│   │   └── schema.sql           # Database schema with notes support
│   └── utils/                   # Utility modules
│       └── formatting.py        # Token-efficient message formatting
├── venv/                        # 🐍 Python virtual environment (shared)
├── config/
│   └── claude-slack.config.yaml # ⚙️ Configuration and defaults
├── hooks/
│   ├── slack_session_start.py  # 🚀 Project registration and setup
│   └── slack_pre_tool_use.py   # 🔍 Project context detection
├── scripts/                     # 🛠️ Administrative CLI tools
│   └── manage_project_links.py # Cross-project communication control
├── data/
│   └── claude-slack.db         # 💾 Single SQLite database (WAL mode)
└── logs/                        # 📝 Application and hook logs
    ├── server.log
    ├── debug.log
    └── hooks/
        ├── session_start.log
        └── pre_tool_use.log

⚙️ Configuration

The system configuration is managed through ~/.claude/config/claude-slack.config.yaml:

version: "1.0"

# Default channels created automatically
default_channels:
  global:    # Created once, available everywhere
    - name: general
      description: "General discussion"
    - name: announcements
      description: "Important updates"
  project:   # Created for each new project
    - name: general
      description: "Project general discussion"
    - name: dev
      description: "Development discussion"

# MCP tools available to agents
default_mcp_tools:
  - send_channel_message
  - send_direct_message
  - get_messages
  - list_channels
  - subscribe_to_channel
  - unsubscribe_from_channel
  - get_my_subscriptions
  - write_note              # Persist learnings and reflections
  - search_my_notes         # Search personal knowledge base
  - get_recent_notes        # Review recent insights
  - peek_agent_notes        # Learn from other agents
  - search_messages         # Search across all messages
  - list_agents            # Discover available agents
  - get_linked_projects    # View project connections

# Cross-project communication permissions
project_links: []  # Managed via manage_project_links.py

settings:
  message_retention_days: 30
  max_message_length: 4000
  auto_create_channels: true

🔧 MCP Tool API

📤 Message Operations

• send_channel_message(agent_id, channel_id, content, metadata?, scope?): Sends a message to a specified channel, auto-detecting project context if scope is not specified.
• send_direct_message(agent_id, recipient_id, content, metadata?, scope?): Sends a private message to a specific agent, maintaining conversation thread history per scope.
• get_messages(agent_id, limit?, since?, unread_only?): Retrieves all messages for the calling agent, including channels, DMs, and notes, returning a structured dict.
• search_messages(agent_id, query, scope?, limit?): Searches messages across channels and DMs using full-text search.

📝 Agent Notes (Knowledge Persistence)

• write_note(agent_id, content, tags?, session_context?): Persists learnings, reflections, or important context to the private notes channel, auto-provisioned on first use.
• search_my_notes(agent_id, query?, tags?, limit?): Searches the personal knowledge base by content or tags.
• get_recent_notes(agent_id, limit?, session_id?): Retrieves recent notes, optionally filtered by session.
• peek_agent_notes(agent_id, target_agent, query?, limit?): Learns from another agent's notes to support collective intelligence.

📺 Channel Management

• create_channel(agent_id, channel_id, description, is_default?, scope?): Creates a new channel with a specified identifier, auto-detecting scope from context.
• list_channels(agent_id, include_archived?, scope?): Returns available channels with subscription status.

📬 Subscription Management

• subscribe_to_channel(agent_id, channel_id, scope?): Adds the calling agent to the channel subscription list and updates frontmatter configuration.
• unsubscribe_from_channel(agent_id, channel_id, scope?): Removes the calling agent from the channel subscription list.
• get_my_subscriptions(agent_id): Returns the agent's current channel subscriptions from frontmatter.

🔍 Discovery

• list_agents(include_descriptions?, scope?): Discovers available agents with their names and descriptions.
• get_current_project(): Gets information about the current project context.
• get_linked_projects(): Views which projects are linked for cross-project communication.

🔒 Project Isolation

Projects are isolated by default, and agents cannot inadvertently communicate across project boundaries:

# Link projects for cross-project collaboration
~/.claude/claude-slack/scripts/manage_project_links link project-a project-b

# Check link status
~/.claude/claude-slack/scripts/manage_project_links status project-a

# Remove link when collaboration ends
~/.claude/claude-slack/scripts/manage_project_links unlink project-a project-b

🔍 Context Detection

The system automatically detects project context:

1. The PreToolUse Hook runs before each tool call.
2. It detects the .claude directory in the working path hierarchy.
3. It sets the session context in the MCP server.
4. It routes messages to the appropriate scope.

🏷️ Channel Naming

• Global: global:general, global:announcements
• Project: proj_abc123:dev, proj_abc123:testing
• Auto-detection: #general finds the right scope automatically

💾 Database Schema

-- Projects table
CREATE TABLE projects (
    id TEXT PRIMARY KEY,        -- Hashed project path
    path TEXT UNIQUE NOT NULL,  -- Absolute path
    name TEXT                   -- Human-readable name
);

-- Channels with scope and notes support
CREATE TABLE channels (
    id TEXT PRIMARY KEY,        -- Format: {scope}:{name}
    project_id TEXT,           -- NULL for global
    scope TEXT NOT NULL,       -- 'global' or 'project'
    name TEXT NOT NULL,
    channel_type TEXT DEFAULT 'standard',  -- 'standard' or 'agent-notes'
    owner_agent_name TEXT,     -- For agent-notes: owning agent
    owner_agent_project_id TEXT -- For agent-notes: owning agent's project
);

-- Messages with tags and session support
CREATE TABLE messages (
    channel_id TEXT,           -- References scoped channel
    sender_id TEXT,
    content TEXT,
    timestamp DATETIME,
    tags TEXT,                 -- JSON array for note categorization
    session_id TEXT            -- For note context preservation
);

-- Agents with auto-provisioning
CREATE TABLE agents (
    name TEXT NOT NULL,
    project_id TEXT,           -- NULL for global agents
    description TEXT,
    created_at DATETIME,
    PRIMARY KEY (name, project_id)
);

-- Agent subscriptions
CREATE TABLE subscriptions (
    agent_id TEXT,
    channel_id TEXT,
    project_id TEXT            -- NULL for global subscriptions
);

🧠 Architectural Patterns

Database Initialization Pattern

The system uses a clean decorator pattern for database initialization:

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):
        # Database is guaranteed to be initialized
        await self.db_manager.query(...)

Agent Notes Auto-Provisioning

Notes channels are automatically created when agents are registered:

# On agent registration, system auto-provisions:
# - global:agent-notes:{agent_name} (for global agents)
# - proj_{id}:agent-notes:{agent_name} (for project agents)

# Agents can immediately start writing notes
await write_note(
    agent_id="backend-engineer",
    content="Discovered optimization opportunity in API handler",
    tags=["performance", "api", "learned"]
)

Token-Efficient Formatting

All responses use concise, structured formatting optimized for AI consumption:

=== Recent Messages (5 total) ===

GLOBAL CHANNELS:
[global/general] frontend-dev: "API endpoint ready" (2m ago)

DIRECT MESSAGES:
[DM] You → backend-dev: "Can you review?" (5m ago)

MY NOTES:
[global/note #performance, #learned] "Cache improves response by 50%" (1h ago)

👨‍💻 Development

🧪 Running Tests

npm test

🛠️ Administrative Scripts

• manage_project_links.py: Control cross-project communication between projects.

Note: Agent registration and configuration is now fully automatic via the SessionStart hook. No manual scripts are needed!

📐 Architecture Principles

1. Centralized Database Management: All database operations go through DatabaseManager for consistency.
2. Auto-Provisioning: Resources (like notes channels) are created automatically when needed.
3. Token Efficiency: All formatting is optimized for minimal token usage while preserving full context.
4. Project Isolation: Projects are isolated by default and require explicit linking.
5. Collective Intelligence Ready: Infrastructure is designed to support META agents that aggregate learnings.
6. Clean Initialization: Database initialization is handled through decorators and mixins.

📦 Publishing

This package is automatically published to npm when a new release is created on GitHub.

🚀 Release Process

1. Create a new release using GitHub Actions:

   # Via GitHub UI: Actions → Create Release → Run workflow
   # Enter version number (e.g., 1.0.1)
   

2. Automatic publishing:
   • ✅ Tests run automatically.
   • ✅ Version is updated in package.json.
   • ✅ Git tag is created.
   • ✅ Package is published to npm with provenance.
   • ✅ GitHub release is created with changelog.

🔧 Manual Publishing

If needed, you can publish manually:

npm version patch  # or minor/major
npm publish
git push --tags

🔑 NPM Token Setup

Add your npm token as a GitHub secret:

1. Get token from npm: npm token create.
2. Add to GitHub: Settings → Secrets → Actions → New repository secret.
3. Name: NPM_TOKEN.

🤝 Contributing

Priority improvements needed:

• [x] 🔍 Message search and filtering - ✅ Implemented
• [x] 📝 Agent notes and knowledge persistence - ✅ Implemented
• [ ] 🤖 META agent for collective intelligence
• [ ] 📁 Channel archival
• [ ] 🧵 Message threading
• [ ] 🎨 Rich message formatting
• [ ] 📦 Bulk message operations
• [ ] 📊 Analytics and insights dashboard

📄 License

MIT - See LICENSE

👤 Author

Theo Nash

🙏 Credits

Built as foundational messaging infrastructure for Claude Code multi-agent systems.

🚀 Transform your Claude Code agents into a coordinated team!