SignalGuard

SignalGuard protects your deep work by intelligently filtering Slack noise and surfacing only what actually needs your attention.

Built for the Slack Agent Builder Challenge using Bolt for Python, Real-Time Search (RTS), Groq LLM reasoning, and MCP Server Integration.

Features

• Protect focus flow — "Protect my focus for 2 hours", /focus 90m, or DM the agent
• RTS-powered scan — Uses assistant.search.context for live workspace context
• LLM reasoning — Groq (llama-3.3-70b-versatile) prioritizes urgent vs important after RTS
• MCP actions — Creates a Focus Canvas via https://mcp.slack.com/mcp (Web API fallback)
• Rich UI — Block Kit summary with Mark done / Defer / Escalate actions
• Native agent UX — Thread titles, suggested prompts, and assistant.threads.setStatus

Quick Start

1. Create Slack App

1. Go to api.slack.com/apps → Create New App → From an app manifest
2. Choose your workspace → paste manifest.json → Create
3. Socket Mode → Enable → generate App-Level Token with scope connections:write
4. Agents & AI Apps → Enable in the app settings sidebar
5. OAuth & Permissions → confirm bot search:read.* scopes are present (add if RTS fails)
6. Install App → Reinstall to Workspace → copy tokens into .env
7. Add judge collaborators: testing@devpost.com, slackhack@salesforce.com

Per Slack manifest docs: do not set "request_url": "" — empty strings fail validation. With Socket Mode enabled, interactivity does not need a Request URL.

2. Configure Environment

cp .env.example .env

Variable	Description
SLACK_BOT_TOKEN	Bot token (xoxb-...) from Install App
SLACK_APP_TOKEN	Full Socket Mode token (xapp-...), not the app ID
SLACK_USER_TOKEN	User token (xoxp-...) for RTS fallback, profile status, MCP
GROQ_CLOUD_API_KEY	Groq API key for LLM categorization

3. Run

Always use the project virtualenv (system python3 will miss dependencies):

cd signalguard
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py

Or without activating:

.venv/bin/python app.py

Confirm you see:

⚡️ Bolt app is running!

4. Test in Slack

Open SignalGuard from the Agents top bar and send:

Protect my focus for the next 2 hours

Usage

Trigger	Example
Assistant thread	"Protect my focus for the next 2 hours"
Slash command	/focus 90m
Suggested prompt	"Protect focus for 2 hours"
End focus	"End focus mode"

Smoke Test (no live Slack events)

source .venv/bin/activate
PYTHONPATH=. python scripts/test_focus_flow.py

Runs sample data → Groq LLM categorization → canvas markdown → Block Kit output.

Project Structure

signalguard/
├── app.py
├── manifest.json
├── src/
│   ├── agent/          # Groq LLM reasoner
│   ├── handlers/       # Bolt event handlers
│   ├── tools/          # RTS + MCP integrations
│   └── utils/          # Canvas, Block Kit, duration, progress
├── docs/
│   ├── architecture.md
│   └── manifest-scopes-addon.md
├── scripts/
│   └── test_focus_flow.py
└── tests/

Required Scopes

Bot: assistant:write, chat:write, commands, canvases:read, canvases:write, channels:history, groups:history, im:history, mpim:history, users:read, search:read.public, search:read.private, search:read.im, search:read.mpim, search:read.files, search:read.users

User: search:read.*, canvases:read, canvases:write, users.profile:write

After changing scopes in the manifest or OAuth page, reinstall the app and update .env tokens.

MCP (optional)

Enable MCP in Agents & AI Apps for your app. Until enabled, canvas creation uses the Slack Web API fallback.

Troubleshooting

Error	Fix
ModuleNotFoundError: dotenv	Use .venv/bin/python app.py, not system python3
missing_scope / search:read.public	Add search scopes to bot token → Reinstall App → refresh .env
invalid_action_token	Reinstall app; SignalGuard retries RTS with user token automatically
ratelimited	RTS uses 2 queries with backoff; wait ~1 min and retry
MCP 400 not enabled	Enable MCP in app settings or rely on Web API canvas fallback

Architecture

See docs/architecture.md.

License

MIT