# Perseus for Slack — Live Context for Developer Teams

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Slack Agent Builder Challenge](https://img.shields.io/badge/Slack-2026_Hackathon-4A154B?logo=slack)](https://slackhack.devpost.com/)

**Perseus brings live project context into Slack via MCP** — answering "what's running?", "what did we decide?", and "where's that code?" so developer teams ship faster without leaving chat.

Built for the **Slack Agent Builder Challenge 2026** (New Slack Agent track) using **Perseus MCP server integration**.

## What it does

- `@perseus services` — check service health from Slack
- `@perseus health` — workspace health report (stale checkpoints, duplicate work)
- `@perseus checkpoint <task>` / `@perseus recover` — save session state, let anyone on the team pick it up
- `@perseus suggest [task]` — AI task recommendation via Pythia (local LLM optional, honestly labeled)
- `@perseus session [N]` — recent session digests
- `@perseus memory <topic>` — recall team decisions and context
- `@perseus search <query>` — find code across the project
- `@perseus onboard` — new team member context dump
- `@perseus ask <question>` — natural language project queries

## Architecture

Dual transport: read-only queries go over MCP; state-changing verbs and the
Pythia suggestion engine go through the Perseus CLI.

```
Slack User → Slack Agent (Bolt) ─┬─ MCP (JSON-RPC 2.0 / HTTP) → Perseus MCP server
                                 │    ├── perseus_services   (health)
                                 │    ├── perseus_get_health (drift, stale/dupe checkpoints)
                                 │    ├── perseus_memory     (Perseus Vault recall)
                                 │    ├── perseus_session    (session digests)
                                 │    ├── perseus_read       (file inspection)
                                 │    ├── perseus_list    ─┐ code search:
                                 │    ├── perseus_read    ─┘ enumerate + grep (client-side)
                                 │    └── ... 31 tools, auto-generated from the directive registry
                                 └─ CLI subprocess → perseus checkpoint / recover / suggest
                                      └── suggest --llm → any OpenAI-compatible endpoint (optional)
```

## Why MCP

The Slack challenge requires MCP server integration, Slack AI, or Real-Time Search. Perseus ships as a **production MCP server** whose directive registry auto-generates **31 tools** (measured via `tools/list`) with zero per-tool schema wiring — we're wiring real infrastructure into Slack, not building a toy.

## AI suggestions — no GPU required

`@perseus suggest` runs Pythia, the Perseus tool oracle. Two modes, always labeled in the Slack response so nobody mistakes one for the other:

| Mode | When | What you see |
|---|---|---|
| ⚡ Live LLM | `PERSEUS_LLM_PROVIDER` set | Model's recommendation + provider/model footer |
| 📊 Deterministic | no LLM configured | Keyword-ranked top skills + "no LLM configured" footer |

Any OpenAI-compatible endpoint works — all CPU-friendly options:

```bash
# Ollama (easiest): ollama pull llama3.2:3b
PERSEUS_LLM_PROVIDER=ollama PERSEUS_LLM_MODEL=llama3.2:3b PERSEUS_LLM_URL=http://localhost:11434

# llama.cpp / LM Studio / Lemonade / vLLM — anything serving /v1/chat/completions
PERSEUS_LLM_PROVIDER=openai-compat PERSEUS_LLM_MODEL=<model-id> PERSEUS_LLM_URL=http://localhost:1234
```

## Quickstart

```bash
pip install -r requirements.txt
pip install perseus-ctx               # Perseus MCP server + CLI

# 1. Start the Perseus MCP server from your project directory
perseus mcp serve --transport sse --port 8420   # set mcp.sse_bearer_token in config.yaml

# 2. Run the Slack agent
cp .env.example .env  # fill in SLACK_BOT_TOKEN, SLACK_APP_TOKEN, PERSEUS_MCP_TOKEN
python src/app.py
```

## Project structure

```
├── src/           # Slack Bolt agent (Python)
│   ├── app.py     # Main app, mentions + slash commands
│   ├── mcp_client.py  # MCP client (Perseus server)
│   ├── handlers.py    # Intent routing
│   └── blocks.py      # Slack Block Kit formatters
├── demo/          # Demo video script + transcript
├── docs/          # Architecture docs + submission
└── assets/        # Architecture diagram
```

## Hackathon

- **Challenge:** [Slack Agent Builder Challenge](https://slackhack.devpost.com/)
- **Track:** New Slack Agent (MCP server integration)
- **Deadline:** July 13, 2026
- **Prize:** $42,000 + Dreamforce trip

## License

MIT — [LICENSE](LICENSE)