nexus-ai

Installation Guide

1. Create the Slack app

  1. Go to api.slack.com/apps → Create New App → From an app manifest.
  2. Select your workspace, paste the contents of backend/slack-manifest/manifest.json.
  3. Review the scopes (already scoped to the minimum needed — see below) and click Create.
  4. Under Basic Information → App-Level Tokens, generate a token with the connections:write scope. This is your SLACK_APP_TOKEN (xapp-...).
  5. Under OAuth & Permissions, click Install to Workspace. Copy the Bot User OAuth Token (xoxb-...) — this is SLACK_BOT_TOKEN.
  6. Under Basic Information → App Credentials, copy the Signing Secret — this is SLACK_SIGNING_SECRET.

Scopes explained (principle of least privilege)

Scope Why NEXUS needs it
commands Register /nexus
chat:write Post messages and ephemeral prompts
im:write, im:history DM-based chat and reminder delivery
channels:history Passive deadline scanning (channels the bot is invited to only)
files:read Download shared PDFs for summarization
team:read, users:read Resolve Slack team/user IDs to internal records

2. Get a Groq API key

  1. Sign up at console.groq.com (free tier).
  2. Create an API key under API Keys → this is GROQ_API_KEY.
  3. Default model is llama-3.3-70b-versatile — fast and free-tier friendly. Change via GROQ_MODEL if needed.

3. Set up Supabase (free tier)

  1. Create a project at supabase.com.
  2. Go to SQL Editor, paste and run backend/src/database/schema.sql.
  3. Go to Project Settings → API — copy the Project URL (SUPABASE_URL) and service_role key (SUPABASE_SERVICE_ROLE_KEY). Keep the service role key secret; it bypasses Row Level Security.

4. Configure environment variables

cd backend
cp .env.example .env

Fill in every value from steps 1–3. SLACK_SOCKET_MODE=true is recommended for local development — no public URL or tunneling tool required.

5. Install and run

npm install
npm run dev

You should see:

⚡️ NEXUS AI is running {"mode":"socket-mode","port":3000,"env":"development"}
Reminder delivery loop scheduled (every minute)
Daily digest job scheduled {"cron":"30 8 * * 1-5","timezone":"Asia/Kolkata"}

6. Invite NEXUS and test

  1. In Slack, invite the bot to a channel: /invite @NEXUS AI.
  2. Try: /nexus task add Review the deck by Friday
  3. Post a message like “let’s finalize this by tomorrow” — you should get a private “Add as task?” prompt within a few seconds.
  4. DM the bot directly to test free-form chat.

Troubleshooting

Symptom Likely cause
App starts but commands do nothing SLACK_APP_TOKEN missing connections:write, or Socket Mode not enabled in app settings
“Invalid environment configuration” on boot A required .env value is missing — the error lists exactly which one
Deadline detection never fires Bot isn’t invited to the channel (channels:history only covers channels it’s a member of)
PDF summarization silently does nothing File isn’t a text-layer PDF, or files:read scope wasn’t granted
This site is open source. Improve this page.