Slack Compass

Autonomous organizational intelligence agent for Slack — built for the Slack Agent Builder Challenge.

Detects what's missing, forgotten, and contradictory in your organization — before it becomes a launch failure, wasted quarter, or customer escalation.

Qualifying technologies

Compass uses two of the challenge's required technologies:

1. Slack AI capabilities — a full AI-app agent surface (agent_view — Slack's Agent messaging experience — with suggested prompts, live status, thread titles) built on Bolt plus a direct-message Q&A path, plus an App Home dashboard.
2. Real-time search API — evidence is collected live via assistant.search.context, with search.messages and seed-corpus fallbacks.

On top of those, a Claude reasoning layer (Anthropic API, structured JSON outputs) grounds every insight and recommendation in the retrieved evidence and routes natural-language questions to the right detector. No key? Compass degrades gracefully to deterministic reasoning.

Architecture

Slack surfaces (agent DM · /compass · proactive events · App Home)
        │
        ▼
Compass Core ── Evidence Collector (assistant.search.context → search.messages → seed)
        │                │
        ▼                ▼
   Detectors ←── Evidence Graph (People · Claims · Decisions · Domains)
        │
        ▼
Claude Reasoning (grounded insight + recommendation, JSON-schema output)
        │
        ▼
Compass Cards (Block Kit) + Watch Engine (continuous re-evaluation, alert on new risk only)

Three detectors:

Detector	Command	Trigger
Missing (Ghost Stakeholder)	/compass ghost <domain>	Launch posts in #ship-it
Memory (Thread Resurrection)	/compass resurrect <topic> — REUSE/REOPEN + CURRENT/STALE decision lifecycle + supersession history	New debate threads
Consistency (Contradiction)	/compass contradict <entity>	On demand / status scan

Plus the agent DM (ask anything in natural language), the App Home dashboard, and /compass watch <entity> for continuous monitoring with resolution notices.

Quick start

1. Offline demo (no tokens at all)

npm install
npm run demo
npm test

2. Run in Slack (Socket Mode)

cp .env.example .env
# Fill SLACK_BOT_TOKEN, SLACK_APP_TOKEN, SLACK_SIGNING_SECRET, ANTHROPIC_API_KEY
# Set COMPASS_MODE=live
npm run dev

Create the app from manifest.json (api.slack.com/apps → Create New App → From a manifest) and enable Agents & AI Apps in the app settings.

3. Seed the sandbox with demo conversations

npm run seed

Creates the demo channels, posts the seed conversations as real messages (so real-time search finds them), and drops a walkthrough card in #judge-demo.

Grant judge access: invite slackhack@salesforce.com and testing@devpost.com as workspace Members.

Try it (live mode)

• DM Slack Compass (Apps → Slack Compass, or the ✨ Agents list) → "Who should be involved in the billing API v2 launch but isn't?"
• /compass ghost payments · /compass resurrect GraphQL for orders · /compass contradict SSO Pro tier
• /compass watch billing API v2 — alerts on new risk, posts when it clears
• Post We're launching billing API v2 on Friday in #ship-it — Compass jumps in proactively
• Open the App Home tab for the org-health dashboard

Scripted fallback (canned data): /compass demo status|ghost|resurrect|contradict|watch

Project structure

src/
  compass-core/     # Orchestrator + status cache
  evidence/         # Real-time search collector + evidence graph
  reasoning/        # Claude reasoning engine + deterministic confidence scorer
  detectors/        # Missing, Memory, Consistency
  watch/            # Watch Engine (alert / resolve lifecycle)
  cards/            # Block Kit Compass Cards
  handlers/         # Agent DM + assistant, App Home, /compass, proactive events
scripts/            # Sandbox seeding (npm run seed)
config/             # Channels + seed hints
seed/               # Demo messages + scenarios

Environment

Required (Slack, Socket Mode):

Variable	Description
SLACK_BOT_TOKEN	Bot token xoxb-...
SLACK_APP_TOKEN	App-level token xapp-... (scope connections:write)
SLACK_SIGNING_SECRET	App signing secret

Optional:

Variable	Default	Description
COMPASS_MODE	demo	live (real-time search + Claude) or demo (seed scenarios)
SLACK_USER_TOKEN	—	User token (search:read.*) — lets real-time search run on every path
SLACK_TEAM_ID	—	Workspace id T… — required on Enterprise Grid sandboxes for channel APIs, notify buttons, and npm run seed
ANTHROPIC_API_KEY	—	Claude reasoning layer — omit for deterministic fallback
COMPASS_LLM_ENABLED	true	Set false to disable Claude even if a key is present
COMPASS_LLM_MODEL	claude-opus-4-8	Override the Claude model
WATCH_INTERVAL_MS	300000	Watch tick interval (5 min)
COMPASS_SEARCH_TIMEOUT_MS	8000	Live-search timeout before falling back to seed
PORT	3000	Health-check server port

Testing & ops

npm test          # unit/integration tests (no network)
npm run typecheck # strict TypeScript check
npm run build     # compile to dist/  →  npm start

A health server runs alongside the bot: GET /api/health (liveness) and GET /api/ready (Socket-Mode connected). It shuts down gracefully on SIGTERM/SIGINT, so it's safe to host on a small VM, Railway, or Fly.io for the long run. See docs/DEPLOYMENT.md for hosting and troubleshooting.

Docs

• docs/IMPLEMENTATION.md — architecture & code guide
• docs/DEPLOYMENT.md — deploy to sandbox
• docs/SANDBOX_SETUP.md — provision developer sandbox
• docs/ARCHITECTURE.md — Mermaid diagrams for Devpost

License

MIT — see LICENSE