notify-slack¶

Sends notifications to Slack when runs start (pre-run) or complete (post-run), with optional file attachments.

Use Cases¶

• Get notified when long-running experiments complete
• Share results automatically with team channels
• Monitor experiment progress across machines
• Attach plots and results to notifications

Setup Requirements¶

Before using this hook, you need to set up a Slack app:

1. Create a Slack App¶

1. Go to api.slack.com/apps
2. Click "Create New App" → "From scratch"
3. Give it a name (e.g., "Capsula Bot") and select your workspace

2. Add Permissions¶

1. Go to "OAuth & Permissions"
2. Under "Bot Token Scopes", add:
3. chat:write - Post messages
4. files:write - Upload files (if using attachments)
5. Click "Install to Workspace"
6. Copy the "Bot User OAuth Token" (starts with xoxb-)

3. Invite Bot to Channel¶

In your Slack channel, type:

/invite @YourBotName

4. Set Environment Variable¶

export SLACK_BOT_TOKEN="xoxb-your-token-here"

Or use a .env file:

SLACK_BOT_TOKEN=xoxb-your-token-here

dotenv = ".env"

Configuration¶

Required Options¶

Optional Options¶

Example¶

[[post-run.hooks]]
id = "notify-slack"
channel = "#experiments"
attachment_globs = ["results/*.png"]

Output Example¶

Successful Notification¶

{
  "__meta": {
    "id": "notify-slack",
    "config": {
      "channel": "C01234567",
      "attachment_globs": ["results/*.png"]
    },
    "success": true
  },
  "message": "Slack notification sent successfully",
  "response": "{\"ok\":true,\"channel\":\"C01234567\",\"ts\":\"1234567890.123456\"}",
  "attachments": [
    "/path/to/results/plot1.png",
    "/path/to/results/plot2.png"
  ]
}

Message Format¶

Pre-Run Message¶

🚀 Capsula Run Starting

Run Name: happy-river
Run ID: 01K8WSYC91YAE21R7CWHQ4KYN2
Timestamp: Jan 9, 2025 at 2:30 PM (UTC)
Command: python train.py --epochs 100

Post-Run Message¶

✅ Capsula Run Completed

Run Name: happy-river
Run ID: 01K8WSYC91YAE21R7CWHQ4KYN2
Timestamp: Jan 9, 2025 at 2:30 PM (UTC)
Command: python train.py --epochs 100

File Attachments¶

Example¶

[[post-run.hooks]]
id = "notify-slack"
channel = "#results"
attachment_globs = ["results/*.png", "plots/*.pdf", "summary.txt"]

Limits¶

• Maximum 10 files per message (Slack API limit)
• If more than 10 files match, only the first 10 are attached

Glob Patterns¶

Same as capture-file:

• *.png - All .png files in current directory
• results/**/*.csv - All CSVs in results/ tree
• plot_?.pdf - plot_1.pdf, plot_2.pdf, etc.

Hook Order with Attachments¶

❌ Wrong Order¶

[[post-run.hooks]]
id = "capture-file"
glob = "report.pdf"
mode = "move"

[[post-run.hooks]]
id = "notify-slack"
channel = "#reports"
attachment_globs = ["report.pdf"]  # File already moved!

✅ Correct Order¶

[[post-run.hooks]]
id = "notify-slack"
channel = "#reports"
attachment_globs = ["report.pdf"]

[[post-run.hooks]]
id = "capture-file"
glob = "report.pdf"
mode = "move"

Troubleshooting¶

"channel_not_found"¶

Invite the bot to the channel: /invite @YourBotName

"invalid_auth" or "not_authed"¶

Check SLACK_BOT_TOKEN environment variable is set and starts with xoxb-

"missing_scope"¶

Add chat:write and files:write scopes, then reinstall the app

Files Not Attaching¶

• Check file paths are correct
• Verify files exist when hook runs
• Check hook order if using capture-file with mode = "move"