Introducing slackker! :fire:

slackker sends real-time notifications, custom updates, and metric plots from any Python script directly to Slack, Telegram, Microsoft Teams, or Discord — so you can step away from the screen and still stay informed. :coffee:

https://github.com/user-attachments/assets/41ab1ee9-4d3c-44d0-82b2-3194acbf7727

Table of contents :notebook:

• Installation
• Quick Start
• Create a Client
• SimpleCallback — any Python function
• Interactive Pipeline
• MCP Server
• Universal MCP Configuration
• Keras
• Lightning
• Support
• Citation
• Maintainer

Installation :arrow_down:

Install slackker from UV (recommended) or pip. Requires Python >= 3.10.

uv add slackker

pip install slackker

Quick Start :rocket:

from slackker.core import TelegramClient
from slackker.callbacks.simple import SimpleCallback

client = TelegramClient(
    token="1234567890:AAAAA_A111BBBBBCCC2DD3eEe44f5GGGgGG",
    verbose=1,
)
notify = SimpleCallback(client)

@notify.notifier
def train_model():
    # ... your training code ...
    return {"accuracy": 0.94, "loss": 0.12}

train_model()

Refer to our website for platform setup instructions (Slack, Telegram, Teams, Discord).

Create a Client

All slackker callbacks use a client object. Create one for your platform and pass it to any callback.

from slackker.core import SlackClient, TelegramClient, TeamsClient, DiscordClient

# Slack
client = SlackClient(
    token="xoxb-123234234235-123234234235-adedce74748c3844747aed",
    channel_id="C04AAB77ABC",
    verbose=0,
)

# Telegram
client = TelegramClient(
    token="1234567890:AAAAA_A111BBBBBCCC2DD3eEe44f5GGGgGG",
    verbose=0,
)

# Discord
client = DiscordClient(
    token="your_bot_token_here",
    channel_id="123456789012345678",
    verbose=0,
)

# Microsoft Teams
client = TeamsClient(
    app_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    tenant_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    chat_id="19:xxxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxx@thread.v2",
    verbose=0,
)

First-time Teams setup: On the first run, TeamsClient prints a short URL and a code. Visit the URL, enter the code, and sign in. The token is then cached and silently refreshed on every subsequent run.

SimpleCallback — any Python function

from slackker.core import TelegramClient
from slackker.callbacks.simple import SimpleCallback

client = TelegramClient(
    token="1234567890:AAAAA_A111BBBBBCCC2DD3eEe44f5GGGgGG",
    verbose=1,
)
notify = SimpleCallback(client)

# Decorator — automatically sends function name, execution time, and return value
@notify.notifier
def train():
    # ... your training code ...
    return {"accuracy": 0.94, "loss": 0.12}

train()

# notify() — send a custom update anywhere, with optional file attachment
notify.notify(
    event="training_complete",
    attachment="./artifacts/model.ckpt",
    best_val_loss=0.0123,
    epoch=20,
)

Works with any client: SlackClient, TelegramClient, TeamsClient, or DiscordClient.

Async: use await notify.async_notify(event="step_done", accuracy=0.95) in async contexts.

Interactive Pipeline

Use ask() to send a message and wait for the user's reply — ideal for checkpoints, confirmations, or human-in-the-loop pipelines:

from slackker.core import TelegramClient
from slackker.callbacks.simple import SimpleCallback

client = TelegramClient(
    token="1234567890:AAAAA_A111BBBBBCCC2DD3eEe44f5GGGgGG",
    verbose=1,
)
notifier = SimpleCallback(client)

def pipeline():
    notifier.notify(event="preprocessing_done", samples=10000)

    reply = notifier.ask("Preprocessing done. Start training? (yes/no)")
    if reply.lower() != "yes":
        return

    # ... training ...
    notifier.notify(event="training_complete", accuracy=0.94)

pipeline()

Async version: use await notifier.async_ask("...") in async contexts.

MCP Server

Use slackker as an MCP server so AI agents can call tools like a remote SimpleCallback:

• notify → send event notifications (optional attachment + metadata)
• ask → human approval gate (continue / halt)
• get_messages → fetch recent channel messages
• get_status → connection + listener status

Install MCP extras:

pip install "slackker[mcp]"

Start the server (stdio transport):

slackker-mcp

CLI run methods

If slackker-mcp is not on your shell PATH, use one of these:

# Run via uv in the current project environment
uv run slackker-mcp

# Run as a Python module (bypasses PATH lookup)
python -m slackker.mcp.server

You can also configure everything with CLI flags only:

slackker-mcp --platform slack --token xoxb-... --channel-id C04AAB77ABC

Or load config from a JSON file and still override via flags:

slackker-mcp --config ./slackker_mcp.json --poll-interval 1.0

Configuration is read from environment variables:

# Required for Slack / Telegram / Discord
SLACKKER_PLATFORM=slack          # slack | telegram | discord | teams
SLACKKER_TOKEN=xoxb-...          # required for slack/telegram/discord

# Platform-specific target
SLACKKER_CHANNEL_ID=C04AAB77ABC  # Slack / Discord channel ID
SLACKKER_CHAT_ID=123456          # Telegram chat ID (optional if auto-discovery works)

# Teams-specific
SLACKKER_APP_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SLACKKER_TENANT_ID=common
SLACKKER_CHAT_ID=19:...@thread.v2

# Optional runtime tuning
SLACKKER_POLL_INTERVAL=2.0
SLACKKER_VERBOSE=1

slackker-mcp automatically reads a local .env file from the current working directory. If the same SLACKKER_* key is set in both places, the exported process environment value wins.

Universal MCP Configuration

slackker-mcp runs as a local stdio MCP server, so it works with MCP clients that can launch a local command.

Compatibility Matrix

Snippets by client

{
  "servers": {
    "slackker": {
      "type": "stdio",
      "command": "slackker-mcp",
      "env": {
        "SLACKKER_PLATFORM": "slack",
        "SLACKKER_TOKEN": "xoxb-...",
        "SLACKKER_CHANNEL_ID": "C04AAB77ABC"
      }
    }
  }
}

{
  "context_servers": {
    "slackker": {
      "command": {
        "path": "slackker-mcp",
        "env": {
          "SLACKKER_PLATFORM": "slack",
          "SLACKKER_TOKEN": "xoxb-...",
          "SLACKKER_CHANNEL_ID": "C04AAB77ABC"
        }
      }
    }
  }
}

{
  "mcpServers": {
    "slackker": {
      "command": "slackker-mcp",
      "env": {
        "SLACKKER_PLATFORM": "slack",
        "SLACKKER_TOKEN": "xoxb-...",
        "SLACKKER_CHANNEL_ID": "C04AAB77ABC"
      }
    }
  }
}

claude mcp add --transport stdio \
  --env SLACKKER_PLATFORM=slack \
  --env SLACKKER_TOKEN=xoxb-... \
  --env SLACKKER_CHANNEL_ID=C04AAB77ABC \
  slackker -- slackker-mcp

{
  "mcpServers": {
    "slackker": {
      "type": "stdio",
      "command": "slackker-mcp",
      "env": {
        "SLACKKER_PLATFORM": "slack",
        "SLACKKER_TOKEN": "xoxb-...",
        "SLACKKER_CHANNEL_ID": "C04AAB77ABC"
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "slackker": {
      "type": "local",
      "command": ["slackker-mcp"],
      "enabled": true,
      "environment": {
        "SLACKKER_PLATFORM": "slack",
        "SLACKKER_TOKEN": "xoxb-...",
        "SLACKKER_CHANNEL_ID": "C04AAB77ABC"
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "slackker": {
      "type": "local",
      "command": ["slackker-mcp", "--config", "/absolute/path/slackker_mcp.json"],
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "slackker": {
      "command": "slackker-mcp",
      "env": {
        "SLACKKER_PLATFORM": "slack",
        "SLACKKER_TOKEN": "xoxb-...",
        "SLACKKER_CHANNEL_ID": "C04AAB77ABC"
      }
    }
  }
}

{
  "mcpServers": {
    "slackker": {
      "command": "slackker-mcp",
      "env": {
        "SLACKKER_PLATFORM": "slack",
        "SLACKKER_TOKEN": "xoxb-...",
        "SLACKKER_CHANNEL_ID": "C04AAB77ABC"
      }
    }
  }
}

Use with Keras

from slackker.core import TelegramClient
from slackker.callbacks.keras import KerasCallback

client = TelegramClient(
    token="1234567890:AAAAA_A111BBBBBCCC2DD3eEe44f5GGGgGG",
    verbose=1,
)
slackker = KerasCallback(
    client=client,
    model_name="MyModel",
    export="png",
    send_plot=True,
)

history = model.fit(
    x_train, y_train,
    epochs=10,
    batch_size=32,
    validation_data=(x_val, y_val),
    callbacks=[slackker],
)

Works with any client: SlackClient, TelegramClient, TeamsClient, or DiscordClient.

Use with Lightning

Unlike Keras, Lightning requires you to explicitly log metrics using self.log() inside your LightningModule. Use on_epoch=True in training_step so slackker can read them at the end of each epoch.

import torch
import torch.nn as nn
from torch.utils.data import DataLoader
import torchvision as tv
import torch.nn.functional as F
from lightning.pytorch import LightningModule, Trainer

from slackker.core import TelegramClient
from slackker.callbacks.lightning import LightningCallback


class LightningModel(LightningModule):
    def __init__(self):
        super().__init__()
        self.fc1 = nn.Linear(28 * 28, 256)
        self.fc2 = nn.Linear(256, 128)
        self.out = nn.Linear(128, 10)

    def forward(self, x):
        batch_size, _, _, _ = x.size()
        x = x.view(batch_size, -1)
        x = F.relu(self.fc1(x))
        x = F.relu(self.fc2(x))
        return self.out(x)

    def configure_optimizers(self):
        return torch.optim.Adam(self.parameters(), lr=1e-3)

    def training_step(self, batch, batch_idx):
        x, y = batch
        y_hat = self.forward(x)
        loss = F.cross_entropy(y_hat, y)
        accuracy = (torch.max(y_hat, 1)[1] == y).float().mean()
        # log with on_epoch=True so slackker can read them at epoch end
        self.log("train_loss", loss, on_epoch=True)
        self.log("train_acc", accuracy, on_epoch=True)
        return loss

    def validation_step(self, batch, batch_idx):
        x, y = batch
        y_hat = self.forward(x)
        loss = F.cross_entropy(y_hat, y)
        accuracy = (torch.max(y_hat, 1)[1] == y).float().mean()
        # on_epoch=True by default in validation_step
        self.log("val_loss", loss)
        self.log("val_acc", accuracy)
        return loss


train_data = tv.datasets.MNIST(".", train=True, download=True, transform=tv.transforms.ToTensor())
val_data = tv.datasets.MNIST(".", train=False, download=True, transform=tv.transforms.ToTensor())
train_loader = DataLoader(train_data, batch_size=128)
val_loader = DataLoader(val_data, batch_size=128)

model = LightningModel()

client = TelegramClient(
    token="1234567890:AAAAA_A111BBBBBCCC2DD3eEe44f5GGGgGG",
    verbose=1,
)
slackker = LightningCallback(
    client=client,
    model_name="MyModel",
    track_logs=["train_loss", "train_acc", "val_loss", "val_acc"],
    monitor="val_loss",
    export="png",
    send_plot=True,
)

trainer = Trainer(max_epochs=10, callbacks=[slackker])
trainer.fit(model, train_loader, val_loader)

Works with any client: SlackClient, TelegramClient, TeamsClient, or DiscordClient.

Support :sparkles:

If you get stuck, we’re here to help. The following are the best ways to get assistance working through your issue:

• Use our Github Issue Tracker for reporting bugs or requesting features. Contribution are the best way to keep slackker amazing :muscle:
• If you want to contribute please refer Contributor's Guide for how to contribute in a helpful and collaborative way :innocent:

Citation :page_facing_up:

Please cite slackker in your publications if this is useful for your project/research. Here is an example BibTeX entry:

@misc{siddheshgunjal2023slackker,
  title={slackker},
  author={Siddhesh Gunjal},
  year={2023},
  howpublished={\url{https://github.com/siddheshgunjal/slackker}},
}

Maintainer :sunglasses: