Slack Integration - Watercooler

Watercooler integrates with Slack to send notifications when threads are created or updated, keeping your team informed in real-time.

Overview

Slack notifications are triggered by:

New entries (say command)
Ball flips (responsibility handoffs)
Status changes (OPEN → CLOSED, etc.)
Handoffs (explicit ball transfers)

Notifications are sent via Slack Incoming Webhooks, requiring no complex OAuth or app installation.

Setup

Step 1: Create Slack App

Go to https://api.slack.com/apps?new_app=1

Click “Create New App” → “From scratch”

Name your app: “Watercooler”

Select your workspace

Click “Create App”

Step 2: Enable Incoming Webhooks

In your app settings, go to “Incoming Webhooks”

Toggle “Activate Incoming Webhooks” to On

Click “Add New Webhook to Workspace”

Select the channel where you want notifications (e.g., #engineering-threads)

Click “Allow”

Step 3: Copy Webhook URL

You’ll see a webhook URL like:

https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX

Copy this URL.

Step 4: Configure Watercooler

Run the setup command:

watercooler slack setup

Interactive setup:

Slack Webhook Setup
========================================

To get a webhook URL:
1. Go to https://api.slack.com/apps?new_app=1
2. Create app 'From scratch', name it 'Watercooler'
3. Go to 'Incoming Webhooks' → Toggle On
4. Click 'Add New Webhook to Workspace'
5. Select channel and authorize

Paste your webhook URL: https://hooks.slack.com/services/T.../B.../...
Testing webhook... ✓
✓ Saved to /home/user/.watercooler/config.toml

Slack notifications enabled:
  ✓ New entries (say)
  ✓ Ball flips
  ✓ Status changes
  ✓ Handoffs

Or pass the webhook URL directly:

watercooler slack setup --webhook-url "https://hooks.slack.com/services/T.../B.../..."

Step 5: Verify Configuration

watercooler slack status

Output:

Slack Integration Status
========================================
Webhook:  ✓ Configured (https://hooks.slack.com/serv...)

Notifications:
  say:           ✓
  ball_flip:     ✓
  status_change: ✓
  handoff:       ✓

Rate limit: 1.0s between notifications

Testing

Send a test notification:

watercooler slack test

Output:

Testing webhook... ✓ Message sent!

You should see a test message in your Slack channel:

🧪 Test message from watercooler CLI

Notification Types

New Entry (Say)

Triggered by watercooler say:

watercooler say api-design \
  --agent "Alice" \
  --title "Decision: Using GraphQL" \
  --body "After evaluation, decided to use GraphQL for better flexibility."

Slack message:

💬 New Entry in api-design

Alice (planner): Decision: Using GraphQL

> After evaluation, decided to use GraphQL for better flexibility.

🏀 Ball → team

Ball Flip

Triggered when ball ownership changes:

watercooler say bug-fix \
  --agent "Bob" \
  --title "Fix implemented" \
  --body "Fixed the auth bug. Ready for review."

Slack message:

🏀 Ball Flip in bug-fix

Bob passed to team

> Fix implemented - ready for review

Status Change

Triggered by watercooler set-status:

watercooler set-status feature-x CLOSED

Slack message:

✅ Status Change: feature-x

OPEN → CLOSED

Feature implementation complete

Handoff

Triggered by watercooler handoff:

watercooler handoff design-review \
  --agent "Alice" \
  --note "Ready for your review, Bob"

Slack message:

👉 Handoff in design-review

Alice → codex

> Ready for your review, Bob

Configuration

Config File Location

Slack settings are stored in:

~/.watercooler/config.toml

Config Structure

[mcp.slack]
webhook_url = "https://hooks.slack.com/services/T.../B.../..."
notify_on_say = true
notify_on_ball_flip = true
notify_on_status_change = true
notify_on_handoff = true
min_notification_interval = 1.0  # seconds between notifications

Environment Variable

Alternatively, set via environment variable:

export WATERCOOLER_SLACK_WEBHOOK="https://hooks.slack.com/services/T.../B.../..."

Environment variable takes precedence over config file.

Customization

Disable Specific Notifications

Edit ~/.watercooler/config.toml:

[mcp.slack]
webhook_url = "https://hooks.slack.com/services/T.../B.../..."
notify_on_say = true
notify_on_ball_flip = false  # Disable ball flip notifications
notify_on_status_change = true
notify_on_handoff = false    # Disable handoff notifications

Adjust Rate Limiting

Prevent notification spam:

[mcp.slack]
webhook_url = "https://hooks.slack.com/services/T.../B.../..."
min_notification_interval = 5.0  # Wait 5 seconds between notifications

Multiple Channels

To send notifications to different channels, create multiple webhooks:

Create webhooks for each channel in Slack app settings
Use environment variables for context-specific webhooks:

# Critical updates to #engineering
export WATERCOOLER_SLACK_WEBHOOK="https://hooks.slack.com/services/T.../B1.../..."
watercooler set-status critical-bug CLOSED

# Regular updates to #threads
export WATERCOOLER_SLACK_WEBHOOK="https://hooks.slack.com/services/T.../B2.../..."
watercooler say regular-task --title "Progress update"

Advanced Integration

MCP Server Notifications

If using the MCP server, notifications are sent automatically:

from watercooler_mcp.slack_notify import notify_slack

# Automatic notifications on thread operations
await notify_slack(
    event="say",
    thread_topic="api-design",
    agent="Alice",
    title="New entry",
    body="Entry content...",
    ball="team"
)

Custom Notification Format

For custom integrations, use the webhook directly:

import requests
import json

webhook_url = "https://hooks.slack.com/services/T.../B.../..."

payload = {
    "text": "🎉 Custom Watercooler Event",
    "blocks": [
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "*Thread:* api-design\n*Event:* Custom event\n*Details:* Something important happened"
            }
        }
    ]
}

requests.post(
    webhook_url,
    data=json.dumps(payload),
    headers={"Content-Type": "application/json"}
)

Thread Summary Digests

Send periodic summaries:

# Create a cron job
crontab -e

# Add daily digest at 9 AM
0 9 * * * /path/to/send-digest.sh

send-digest.sh:

#!/bin/bash
OPEN_THREADS=$(watercooler list --open-only | wc -l)
NEW_THREADS=$(watercooler list --threads-dir ./threads | grep NEW | wc -l)

curl -X POST "$WATERCOOLER_SLACK_WEBHOOK" \
  -H "Content-Type: application/json" \
  -d "{
    \"text\": \"📊 Daily Watercooler Digest\",
    \"blocks\": [
      {
        \"type\": \"section\",
        \"text\": {
          \"type\": \"mrkdwn\",
          \"text\": \"*Open Threads:* $OPEN_THREADS\\n*New Activity:* $NEW_THREADS threads\"
        }
      }
    ]
  }"

Disabling Notifications

Temporary Disable

Unset environment variable:

unset WATERCOOLER_SLACK_WEBHOOK

Permanent Disable

watercooler slack disable

Output:

✓ Slack notifications disabled.
  Config updated: /home/user/.watercooler/config.toml

This clears the webhook URL from your config file.

Troubleshooting

Webhook URL Invalid

If you see “Invalid webhook URL format”:

watercooler slack setup

Ensure the URL starts with:

https://hooks.slack.com/services/

Test Failed

If test notification fails:

Check webhook URL: Verify it’s correct in config
```
cat ~/.watercooler/config.toml
```
Verify webhook is active: Go to Slack app settings → Incoming Webhooks

Check network connectivity:

curl -X POST "$WATERCOOLER_SLACK_WEBHOOK" \
  -H "Content-Type: application/json" \
  -d '{"text": "Test"}'

No Notifications Received

If commands run but no Slack messages appear:

Verify configuration:
```
watercooler slack status
```
Check notification settings: Ensure the event type is enabled
```
notify_on_say = true  # Must be true
```
Test explicitly:
```
watercooler slack test
```
Check rate limiting: If sending many notifications rapidly, they may be rate-limited

Rate Limited by Slack

Slack limits webhook requests to ~1 per second. If you see 429 errors:

Increase min_notification_interval:
```
min_notification_interval = 2.0
```
Batch operations: Group multiple updates before notifying

tomlkit Not Available

If you see “tomlkit required”:

pip install tomlkit

Best Practices

1. Use Dedicated Channel

Create a specific channel for thread notifications:

#watercooler-threads

This prevents notification fatigue in general channels.

2. Configure Rate Limiting

For active projects:

min_notification_interval = 2.0  # Limit to 1 notification per 2 seconds

3. Disable Noisy Events

If ball flips happen frequently:

notify_on_ball_flip = false  # Keep only important notifications

4. Use Thread Mentions

Include relevant people in notifications:

watercooler say api-review \
  --title "@alice Ready for your review" \
  --body "Completed implementation as discussed."

5. Test Before Production

Always test webhooks before using in CI/CD:

watercooler slack test

Security

Protect Webhook URL

Treat webhook URLs as secrets:

Don’t commit to version control
Use environment variables in CI/CD
Rotate regularly if exposed

Regenerate Webhook

If webhook is compromised:

Go to Slack app settings → Incoming Webhooks
Delete the compromised webhook
Create a new webhook

Update Watercooler config:

watercooler slack setup --webhook-url "<new-url>"

Integration with CI/CD

GitHub Actions

name: Watercooler Thread Update
on:
  push:
    branches: [main]

jobs:
  update-thread:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Update thread
        env:
          WATERCOOLER_SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
        run: |
          pip install watercooler
          watercooler say deployment-main \
            --agent "GitHub Actions" \
            --title "Deploy to production" \
            --body "Commit: $GITHUB_SHA. Deployed successfully."

GitLab CI

update-thread:
  script:
    - pip install watercooler
    - watercooler say deployment-main
        --agent "GitLab CI"
        --title "Deploy complete"
        --body "Pipeline $CI_PIPELINE_ID succeeded"
  variables:
    WATERCOOLER_SLACK_WEBHOOK: $SLACK_WEBHOOK_URL

Get Started

Core Concepts

Setup & Configuration

Guides

​Overview

​Setup

​Testing

​Notification Types

​New Entry (Say)

​Ball Flip

​Status Change

​Handoff

​Configuration

​Config File Location

​Config Structure

​Environment Variable

​Customization

​Disable Specific Notifications

​Adjust Rate Limiting

​Multiple Channels

​Advanced Integration

​MCP Server Notifications

​Custom Notification Format

​Thread Summary Digests

​Disabling Notifications

​Temporary Disable

​Permanent Disable

​Troubleshooting

​Webhook URL Invalid

​Test Failed

​No Notifications Received

​Rate Limited by Slack

​tomlkit Not Available

​Best Practices

​1. Use Dedicated Channel

​2. Configure Rate Limiting

​3. Disable Noisy Events

​4. Use Thread Mentions

​5. Test Before Production

​Security

​Protect Webhook URL

​Regenerate Webhook

​Integration with CI/CD

​GitHub Actions

​GitLab CI

​Next Steps

Multi-Agent Workflows

Branch Pairing

Build docs developers (and LLMs) love

Overview

Setup

Testing

Notification Types

New Entry (Say)

Ball Flip

Status Change

Handoff

Configuration

Config File Location

Config Structure

Environment Variable

Customization

Disable Specific Notifications

Adjust Rate Limiting

Multiple Channels

Advanced Integration

MCP Server Notifications

Custom Notification Format

Thread Summary Digests

Disabling Notifications

Temporary Disable

Permanent Disable

Troubleshooting

Webhook URL Invalid

Test Failed

No Notifications Received

Rate Limited by Slack

tomlkit Not Available

Best Practices

1. Use Dedicated Channel

2. Configure Rate Limiting

3. Disable Noisy Events

4. Use Thread Mentions

5. Test Before Production

Security

Protect Webhook URL

Regenerate Webhook

Integration with CI/CD

GitHub Actions

GitLab CI

Next Steps