HiveMind

A multi-agent AI team that lives in your Discord server. Define any number of agents — each with a custom role, personality, and system prompt — pick one as the "decider," and let them discuss, debate, and decide on whatever you throw at them.

HiveMind orchestrates a configurable team of LLM-powered agents through a structured workflow (intake brief → multi-round discussion → optional debate → decider summary) and streams the result into a Discord channel in real time. A companion web app lets you manage teams, add or remove agents, set speaking order and the decider role, and bind channels to teams without leaving the browser.

Features

• Role-agnostic agent workflow built on LangGraph + CrewAI. Define as many agents as you want with any role — the graph adapts automatically. Discussion happens in two rounds; if agents disagree, the graph escalates into a structured debate before the decider makes the call.
• Default 5-agent template (PM, Engineer, Marketing, Finance, CEO) ships out of the box. Add, remove, or replace agents from the web UI or API.
• display_order + is_decider controls. The first non-decider agent opens the conversation (intake), remaining non-decider agents contribute in display_order, and the designated decider writes the final summary.
• Discord-first UX. /discuss, /debate, /ask, /create-team, /myteam slash commands. Responses stream into a per-conversation thread with thinking placeholders and reaction-driven follow-ups.
• Web management UI (Next.js 14). Browse teams, add/edit/delete agents (with display order and decider toggle), view full conversation transcripts, bind/unbind Discord channels.
• Channel binding model — one Discord channel = one active team at a time, enforced by a Postgres partial unique index. Teams can be reused across channels.
• One-click bot install. The web app generates the OAuth URL; the bot auto-registers slash commands the moment it joins a new server.
• Server-Sent Events stream agent responses as they finish, so users see partial progress instead of waiting for the full graph to complete.

Architecture

┌──────────┐    SSE     ┌─────────┐    LangGraph    ┌────────────┐
│ Discord  │ <────────> │ Backend │ ──────────────> │  CrewAI    │
│   Bot    │            │ FastAPI │                 │   Agents   │
└──────────┘            └────┬────┘                 └────────────┘
                             │
┌──────────┐                 │
│  Web UI  │ <──REST/CORS───>│
│ Next.js  │                 │
└──────────┘                 v
                        ┌────────┐
                        │Postgres│
                        └────────┘

Graph topology

START → intake → discussion_loop → check_disagreement
    [disagreement / mode=debate] → debate → decider_summary → END
    [no disagreement]            → decider_summary → END

• intake — first non-decider agent (by display_order) frames the problem and @mentions each contributor.
• discussion_loop — remaining non-decider agents respond in two rounds, reacting to each other.
• debate — all non-decider agents argue positions in two rounds (only if disagreement detected or mode is debate).
• decider_summary — the agent flagged is_decider reads all outputs and issues DECISION / WHY / NEXT.

Directory structure

• backend/ — FastAPI + SQLAlchemy async + Alembic. Hosts the LangGraph workflow, REST endpoints, and SSE streaming.
• discord-bot/ — discord.js v14. Slash commands, threaded responses, reaction handlers, auto-registration on guild join.
• web/ — Next.js 14 (App Router) + Tailwind + TanStack Query + NextAuth (Discord provider). Teams, Agents, and Conversations screens.

Quick start (Docker)

git clone <this repo>
cd hivemind
cp .env.example .env
# fill in OPENAI_API_KEY, DISCORD_TOKEN, CLIENT_ID,
# DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET, NEXTAUTH_SECRET
docker compose up -d

Then:

1. Open http://localhost:3000 and sign in with Discord.
2. Click + New team to create a team (ships with the default 5-agent roster).
3. Optionally add, remove, or reconfigure agents from the team detail page — set display_order and toggle which agent is the decider.
4. Open Conversations → + New conversation, pick the team, click + Add bot to a server to install the bot, then pick a channel to bind.
5. In Discord, run /discuss message: <whatever you want to discuss> in that channel.

What you'll need from Discord

In https://discord.com/developers/applications, create an application and:

• Bot tab — create a bot, copy the token → DISCORD_TOKEN. Toggle on Message Content Intent and Server Members Intent.
• OAuth2 tab — copy Client ID → CLIENT_ID and DISCORD_CLIENT_ID, copy Client Secret → DISCORD_CLIENT_SECRET. Add http://localhost:3000/api/auth/callback/discord under Redirects.

Environment variables

Var	Where	Purpose
OPENAI_API_KEY	backend	LLM calls (litellm/CrewAI)
OPENAI_MODEL	backend	default gpt-4o-mini
API_KEY	backend, bot, web	shared HMAC for the backend's REST endpoints
DATABASE_URL	backend	postgres connection string
DISCORD_TOKEN	bot, backend	bot token (login + REST calls)
CLIENT_ID	bot	application ID for slash command registration
DISCORD_CLIENT_ID	backend, web	OAuth2 client ID
DISCORD_CLIENT_SECRET	web	OAuth2 client secret (NextAuth)
NEXTAUTH_SECRET	web	NextAuth JWT signing key (openssl rand -base64 32)
NEXTAUTH_URL	web	public URL of the web app
WEB_APP_URL	backend, bot	URL the bot points users to when a channel is unbound

Development

Each service can be run on its own:

# backend
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn main:app --reload

# discord bot
cd discord-bot
npm install
node index.js

# web
cd web
npm install
npm run dev

Run pytest in backend/ for the test suite (36 tests).

Tech stack

• Backend: Python 3.13, FastAPI, SQLAlchemy 2 (async), Alembic, LangGraph, CrewAI, litellm, asyncpg, Pydantic v2
• Bot: Node 20, discord.js 14
• Web: Next.js 14 (App Router), React 18, TypeScript, Tailwind CSS, TanStack Query, NextAuth
• Storage: PostgreSQL 15
• Infra: Docker Compose for everything

Contributing

PRs welcome. The project is small enough to read end-to-end in an afternoon — start with backend/graph/ (the agent workflow) or web/app/ (the UI). Issues and discussions are open.

License

MIT