GitHub - eoffermann/BigBlueBam: The work suite built for human-AI teams.

The work suite built for human-AI teams.
Your team sets the strategy. AI agents handle the routine. Everyone works in the same place.

Vision • At a Glance • Tour • For Teams • For AI Agents • Banter • Helpdesk • Beacon • Brief • Bolt • Bearing • Board • Bond • Blast • Bench • Book • Blank • Bill • Quick Start • Architecture • Docs

The Vision

Most work platforms are built for humans talking to humans. BigBlueBam is built for human-AI collaboration, a world where your team and AI agents plan projects, message each other, close deals, write docs, track goals, automate workflows, and support customers in the same suite, at the same time.

Humans own the strategy: setting priorities, defining epics, closing deals, reviewing deliverables, talking to customers.

AI agents own the routine: triaging helpdesk tickets, writing knowledge base articles, drafting documents, updating CRM pipelines, generating sprint reports, firing workflow automations, and keeping the board organized.

The suite is the shared workspace. When an AI agent creates a task, replies to a customer, updates a deal, or posts to a Banter channel, it shows up in real time, right alongside everything your team is doing. No separate dashboards. No hidden automation. Full transparency.

This is made possible by 340 MCP tools that give AI assistants (Claude, Claude Code, custom agents) full read-write access to project boards, sprints, team messaging (with scheduled posts and pattern subscriptions), helpdesk tickets, knowledge base, collaborative docs, workflow automations with runtime observability, goals and OKRs, whiteboards, CRM pipelines with dedupe, email campaigns, analytics dashboards, scheduling with mixed human-and-agent rosters, forms, invoicing, plus cross-cutting platform capabilities (cross-app search, composite subject views, entity linking, durable proposal queues, per-agent kill switches, HMAC-signed outbound webhooks). Service-account agents run behind a fail-closed policy gate with confirm-action tokens backed by Redis so destructive flows survive rolling deploys.

The Suite at a Glance

Fourteen apps, one workspace. If you've used the tools on the right you already know most of how each app works — the difference is that all fourteen live under the same auth, the same org and project permissions, and the same 340-tool MCP surface, so AI agents can work across them without integration glue.

What the comparison table doesn't show: every one of these apps is wired into the same MCP surface, so an AI agent triaging a Helpdesk ticket can upsert the requester in Bond, create a Bam task, post a Banter update to the engineering channel, and schedule a Book meeting with the customer — in one cross-app flow, with visibility preflight and a durable approval queue gating anything destructive.

Product Tour

The Kanban board — the central hub where human and AI work converges.

Timeline / Gantt view	Calendar view
List / table view	Project analytics dashboard
Helpdesk ticket list	Command palette (Ctrl+K)

For Teams

Kanban Board

Drag-and-drop cards across 5 configurable phases with WIP limits. Each card shows priority, assignee, story points, due date, and comment count at a glance. Motion spring physics make the interactions feel natural.

Dark mode — the default for late-night deploys.

Light mode — because some people like the sun.

Swimlanes

Group tasks by assignee, priority, or epic. Collapsible rows show task count and total story points per group, making it easy to spot bottlenecks and unbalanced workloads.

Five Views, One Board

Every project supports five views — switch between them without losing your filters or context:

Calendar view — monthly navigation with task due dates

Task Detail

Click any card to open the detail drawer. Full rich-text description with image support, assignee, priority, phase, sprint, story points, start and due dates, subtasks, file attachments, comments with emoji reactions, and a complete activity feed.

Sprint Management

Create sprints, assign tasks, track velocity. When a sprint ends, the carry-forward ceremony moves incomplete work to the next sprint automatically. Sprint reports show burndown, velocity trends, and completion rates.

Project Dashboard

Charts and widgets for sprint progress, priority breakdown, overdue tasks, task distribution by phase, and team workload — all in one place.

My Work

A cross-project view of everything assigned to you, grouped by project. One place to see your full plate.

Command Palette

Press Ctrl+K to open the command palette. Search tasks, switch projects, navigate views, and trigger actions without touching the mouse.

Organization Management

BigBlueBam ships a dedicated People surface (not buried under Settings) that covers the full identity lifecycle — invite, edit, assign, disable — with strict role-based gating.

Filter by role or status, search by name or email, and act on individual members or in bulk.

Per-user detail, four tabs

Admins can reset passwords (manual or auto-generated), mint API keys on behalf of users with scoped permissions, force a password change on next login, or sign the user out of every device.

Bulk operations

Select multiple members to disable, enable, change role, remove from org, or export as CSV — all with rank-gating that mirrors the server:

Multi-org membership

Users can belong to multiple organizations. The header shows the current org + role, and the org switcher lets multi-org users hop between them in one click — the session rotates and every query is invalidated, so the rest of the app instantly reflects the new org's data.

A persistent banner warns when an org has no active owner, so operators can promote a replacement before the situation becomes invisible:

SuperUser console

A separate SuperUser namespace at /b3/superuser gives platform operators cross-org visibility without impersonation. See every org on the server, context-switch into any of them, and manage users globally.

Cross-org user management — one view of every user regardless of org:

Audit log — every SuperUser action against this user with expandable details

When a SuperUser is context-switched into a non-native org, a red banner and chip in the header make the privileged state impossible to miss:

Forced password change

Admins can flag a user to require a password change on their next login. On sign-in, the user is bounced to a dedicated form that blocks every other page until a new password is set:

Theme-aware UI

Every screen adapts to light and dark mode. Most of the shots in this README are dark; here's the same People list in light mode:

Integrations

Configure calendar feeds, API keys, and webhooks under Settings:

For AI Agents

BigBlueBam exposes 340 MCP (Model Context Protocol) tools that give AI assistants full access to every app in the suite plus cross-cutting platform capabilities. Connect Claude, Claude Code, or any MCP-compatible agent and let it work alongside your team.

What AI Agents Can Do

• Create and manage tasks — create tasks, set priority and assignee, move cards across phases, add subtasks, and upsert by external id for idempotent webhook/import flows
• Run sprints — create sprints, assign tasks, start/complete sprints, generate sprint reports
• Triage helpdesk tickets — when a customer submits a ticket, a task is auto-created; AI agents can then triage by adjusting priority, upserting the requester by email, checking for similar open tickets via the dedupe primitives, setting timelines, assigning to the right engineer, and posting responses to customers
• Generate reports — velocity reports, burndown charts, cumulative flow, workload distribution, overdue task alerts, plus phrase-count trend queries across helpdesk tickets and Bam tasks
• Collaborate — post comments, log time, bulk update tasks, suggest branch names
• Message the team via Banter — post messages immediately or schedule for later while respecting per-channel quiet hours, manage channels, react, search conversations and call transcripts, subscribe to message patterns, and participate in voice calls as spoken participants
• Manage the knowledge base via Beacon — create, publish, upsert-by-slug, search with semantic plus graph retrieval, verify content freshness, link related knowledge, manage governance policies, and save reusable queries
• Author collaborative documents via Brief — create, edit, upsert-by-slug, search documents, manage version history, leave inline comments, apply templates, and graduate finished documents into Beacons
• Automate workflows with Bolt — create trigger-condition-action rules, inspect executions, trace why each rule fired or skipped, browse templates, and orchestrate cross-product automations against the full 340-tool catalog
• Track goals and OKRs with Bearing — create time-boxed periods, define goals with key results, link KRs to Bam tasks for automatic progress, post status updates, and generate at-risk reports
• Collaborate visually on Board — create and manage whiteboard rooms, add and arrange shapes, read canvas content for AI analysis, manage participants, embed cross-product content, and run sticky-to-task pipelines
• Manage CRM pipeline with Bond — create, update, upsert-by-email, merge contacts, advance deals through pipeline stages, detect likely duplicates with confidence scores, log activities, and generate pipeline reports
• Run email campaigns with Blast — draft campaigns, build segments, generate templates and subject lines, schedule sends, and pull engagement analytics
• Bill clients with Bill — create invoices from deals or time entries, add line items, record payments, send reminders, and surface profitability and revenue summaries
• Collect with Blank forms — generate form definitions from a prompt, publish forms, export submissions, and summarize free-text responses
• Schedule with Book — create, update, cancel, and RSVP to events, and find meeting times across mixed human-plus-agent rosters
• Analyze with Bench — create dashboards, run ad-hoc queries, schedule reports, detect anomalies, and compare metrics across time periods
• Find anything with cross-app platform tools — search_everything fans out across seven searchable apps with normalized scoring; resolve_references turns free text into ranked entity candidates; account_view / project_view / user_view compose full subject-centric pictures; entity_links_list exposes durable cross-app relationships; activity_query and activity_by_actor read a unified activity log
• Run responsibly — can_access preflights visibility before surfacing entities to askers; proposal_create / proposal_list / proposal_decide drive a durable approval queue; agent_heartbeat tracks runner liveness; agent_policy_set gives operators kill switches and per-agent tool allowlists that fail closed; agent_webhook_configure pushes events to external runners with HMAC-signed retries, SSRF guards, and a dead-letter queue

Example: AI-Powered Helpdesk Triage

A customer submits a bug report through the helpdesk portal. BigBlueBam automatically creates a FRND- prefixed task on the board. An AI agent picks up the new task, analyzes the description, sets priority to High, assigns it to the right engineer based on the related epic, adjusts the timeline, and posts a response to the customer: "Thanks for reporting this — we've assigned task FRND-247 to the team and it's been prioritized. We'll update you when there's a fix."

The engineer sees the triaged card on their board. The customer sees the response in their portal. The task was created automatically; the AI handled the triage.

Example: AI Gathering Details from Vague Reports

A customer submits a ticket: "The app isn't working." BigBlueBam auto-creates a task, and an AI agent picks it up. Recognizing the report lacks actionable detail, the agent responds to the customer through the helpdesk portal:

"Sorry to hear that! To help us investigate, could you provide a few details?

• What were you trying to do when the issue occurred?
• What device and browser are you using? (e.g., iPhone 14 / Safari, Windows / Chrome)
• Does the issue happen every time or intermittently?
• If possible, a screenshot of any error message would be very helpful."

The agent sets the task to waiting_on_customer and adds an internal note for the engineering team: "Vague report — asked customer for repro steps, device info, and screenshots. Will re-triage once details come in." When the customer replies with specifics, the agent updates the task description, sets the appropriate priority, and assigns it to the right engineer — all before a human touches it.

MCP Tools Reference

340 tools across the fourteen apps plus cross-cutting agentic platform surfaces:

MCP Setup

The canonical MCP endpoint is /mcp/ on the public ingress (Streamable HTTP transport). Add this to your Claude Desktop or Claude Code configuration:

{
  "mcpServers": {
    "bigbluebam": {
      "url": "http://localhost/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Or from the Claude Code CLI:

claude mcp add --transport http bigbluebam https://YOUR_DOMAIN/mcp/ \
  --header "Authorization: Bearer YOUR_API_KEY"

Generate an API key from Settings > Integrations in the BigBlueBam UI. For server-to-server integrations, mint a bbam_svc_-prefixed service-account key instead (see the Provision the internal MCP service account section below). /mcp/health returns a liveness JSON with no auth; see docs/mcp-server.md for the full endpoint map.

Bam (Project Management)

undefined routes, undefined schemas

Guide | Overview

Banter (Team Messaging)

undefined routes, undefined schemas

Guide | Overview

Beacon (Knowledge Base)

undefined routes, undefined schemas

Guide | Overview

Bearing (Goals & OKRs)

undefined routes, undefined schemas

Guide | Overview

Bench (Analytics)

undefined routes, undefined schemas

Guide | Overview

Bill (Invoicing)

undefined routes, undefined schemas

Guide | Overview

Blank (Forms)

undefined routes, undefined schemas

Guide | Overview

Blast (Email Campaigns)

undefined routes, undefined schemas

Guide | Overview

Board (Visual Collaboration)

undefined routes, undefined schemas

Guide | Overview

Bolt (Workflow Automation)

undefined routes, undefined schemas

Guide | Overview

Bond (CRM)

undefined routes, undefined schemas

Guide | Overview

Book (Scheduling)

undefined routes, undefined schemas

Guide | Overview

Brief (Documents)

undefined routes, undefined schemas

Guide | Overview

Helpdesk (Support Portal)

undefined routes, undefined schemas

Guide | Overview

AI Provider Configuration

BigBlueBam features a hierarchical LLM provider configuration system that powers AI features across the suite — including Bolt's AI-assisted automation authoring, future summarization, and content generation features.

How It Works

Providers are configured at three levels, with the most specific taking precedence:

Supported Providers

Security

• API keys are encrypted at rest using AES-256-GCM with the server's SESSION_SECRET
• Keys are never returned in full — always redacted to sk-•••XXXX (last 4 characters only)
• Scope-based authorization ensures only the right roles can configure each level
• Test Connection verifies credentials work before saving

Setup

Configure providers in Settings → AI Providers in the Bam frontend. If no provider is configured, AI-dependent features (like Bolt's "Describe your automation" dialog) show a helpful message directing admins to the setup page.

Quick Start

📖 Full deployment guide: docs/deployment-guide.md — step-by-step walkthrough with interactive setup wizard, password generation, and platform selection (Docker Compose for self-hosted; Railway for managed cloud — both fully automated).

Guided Setup (Recommended)

The interactive deploy script handles everything — installs dependencies, generates secrets, provisions infrastructure, and creates your admin account:

git clone https://github.com/eoffermann/BigBlueBam.git
cd BigBlueBam

# Linux / macOS
./scripts/deploy.sh

# Windows (PowerShell)
.\scripts\deploy.ps1

Manual Setup with Docker Compose

If you prefer to set things up manually:

# Clone the repo
git clone https://github.com/eoffermann/BigBlueBam.git
cd BigBlueBam

# Set up environment
cp .env.example .env
# Edit .env with your secrets (passwords, session secret)

# Start all services
docker compose up -d

# Create your admin account
docker compose exec api node dist/cli.js create-admin \
  --email admin@example.com \
  --password YourPassword123 \
  --name "Admin User" \
  --org "My Organization"

Provision the internal MCP service account

Bolt automations and the background worker invoke MCP tools over an internal HTTP path (POST /mcp/tools/call) instead of holding a persistent MCP session. That path is authenticated two ways: a shared secret (INTERNAL_SERVICE_SECRET, already generated by cp .env.example .env or the deploy script) plus a bearer token tied to a dedicated service-account user that mcp-server uses to talk to the rest of the stack on behalf of internal callers.

If MCP_INTERNAL_API_TOKEN is blank in your .env, mcp-server still boots and external MCP clients (Claude Desktop, Claude Code) work fine — but every call to POST /mcp/tools/call returns HTTP 503 with INTERNAL_NOT_CONFIGURED, which means Bolt automations that invoke MCP tools will fail and any worker job relying on the internal path won't be able to call MCP tools either. For a self-hosted single-operator setup you can leave it blank; for anything that needs Bolt-to-MCP integration, provision the token once:

# 1. Mint a service account + API key (prefix bbam_svc_). The --org-slug
#    is the one you created with create-admin above; slugify() lowercases
#    and hyphenates the --org value (e.g. "My Organization" becomes
#    "my-organization"). Run `docker compose exec api node dist/cli.js list-orgs`
#    if you're not sure.
docker compose exec api node dist/cli.js create-service-account \
  --name mcp-internal \
  --org-slug my-organization

# 2. The command prints a token once:
#       Token:      bbam_svc_abcdef0123456789...
#    Copy that value (not the command output around it) and paste it into .env:
#       MCP_INTERNAL_API_TOKEN=bbam_svc_abcdef0123456789...

# 3. Restart mcp-server so it picks up the new env var.
docker compose up -d --force-recreate mcp-server

You only need to do this once per stack. If you wipe the postgres volume you will need to re-mint the token because the service-account user lives in the database. The token is not rotated automatically; to rotate, mint a new service account with a different --name, swap the env var, restart, then delete the old service-account user via docker compose exec api node dist/cli.js revoke-api-key --prefix bbam_svc.

Open http://localhost/b3/ to access BigBlueBam, http://localhost/banter/ for Banter, http://localhost/beacon/ for Beacon, http://localhost/brief/ for Brief, http://localhost/bolt/ for Bolt, http://localhost/bearing/ for Bearing, http://localhost/board/ for Board, http://localhost/bond/ for Bond CRM, or http://localhost/helpdesk/ for the helpdesk portal.

The login page — clean and branded.

After login, you land on the project dashboard:

Services

All services are accessed through a single nginx container on port 80:

Infrastructure services (internal, not exposed via nginx):

Development Mode

pnpm install
pnpm --filter @bigbluebam/shared build
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

Run Tests

pnpm test  # 900+ tests across all packages

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                       Clients (Browser / AI)                         │
└────────────────────────┬──────────────────────┬──────────────────────┘
                         │ HTTP :80              │ WebRTC
┌────────────────────────▼──────────────────────┐│
│               nginx (single container, :80)    ││
│  /b3/          → Bam SPA (static)               ││
│  /b3/api/      → Fastify API :4000             ││
│  /b3/ws        → WebSocket :4000               ││
│  /banter/      → Banter SPA (static)           ││
│  /banter/api/  → Banter API :4002              ││
│  /banter/ws    → Banter WebSocket :4002        ││
│  /beacon/      → Beacon SPA (static)           ││
│  /beacon/api/  → Beacon API :4004              ││
│  /brief/       → Brief SPA (static)            ││
│  /brief/api/   → Brief API :4005               ││
│  /brief/ws     → Brief WebSocket :4005         ││
│  /bolt/        → Bolt SPA (static)             ││
│  /bolt/api/    → Bolt API :4006                ││
│  /bearing/     → Bearing SPA (static)          ││
│  /bearing/api/ → Bearing API :4007             ││
│  /board/       → Board SPA (static)            ││
│  /board/api/   → Board API :4008               ││
│  /board/ws     → Board WebSocket :4008         ││
│  /bond/        → Bond SPA (static)             ││
│  /bond/api/    → Bond API :4009                ││
│  /helpdesk/    → Helpdesk SPA (static)         ││
│  /helpdesk/api/→ Helpdesk API :4001            ││
│  /files/       → MinIO :9000                   ││
│  /mcp/         → MCP Server :3001              ││
└──────┬──────────┬──────────┬───────────────────┘│
       │          │          │                     │
┌──────▼────┐ ┌──▼───────┐ ┌▼──────────┐ ┌──────────┐ ┌───────▼──────┐ ┌──────────┐
│ Bam API   │ │ Banter   │ │ MCP Server│ │ Brief    │ │ Bolt API │ │ LiveKit SFU  │ │ Worker   │
│ :4000     │ │ API :4002│ │ :3001     │ │ API :4005│ │ :4006    │ │ :7880 (voice)│ │ BullMQ   │
│ +WebSocket│ │ +WS      │ │ 340 tools │ │ +WS      │ │          │ │ +voice-agent │ │ jobs     │
└─────┬─────┘ └────┬─────┘ └─────┬─────┘ └────┬─────┘ └──────────────┘ └────┬─────┘
      │             │             │            │                  │
┌─────▼─────────────▼─────────────▼────────────▼───────────────────▼───┐
│  PostgreSQL 16  │  Redis 7        │  MinIO (S3)   │  Qdrant (vectors)    │
│  40+ tables     │  PubSub + cache │  File storage │  Semantic search     │
└──────────────────────┴──────────────────────┴────────────────────────┘

Tech Stack

Monorepo Structure

apps/
  api/              → Bam Fastify REST API + WebSocket (project management core)
  frontend/         → Every React SPA under one container
  mcp-server/       → MCP protocol server (340 tools, Redis-backed confirm tokens)
  worker/           → BullMQ background jobs (emails, notifications, scheduled Banter posts, webhook dispatch + DLQ)
  helpdesk-api/     → Helpdesk Fastify API (tickets, messages, similar-tickets lookup, user upsert)
  banter-api/       → Banter Fastify API + WebSocket (channels, threads, calls, quiet hours, scheduled posts, agent subscriptions)
  beacon-api/       → Beacon Fastify API (knowledge base, search, graph, policies, upsert-by-slug)
  brief-api/        → Brief Fastify REST API + WebSocket (collaborative docs with upsert-by-slug)
  bolt-api/         → Bolt Fastify REST API (workflow automation, rules, executions, event trace, drift detection)
  bearing-api/      → Bearing Fastify REST API (goals, key results, progress, reporting)
  board-api/        → Board Fastify REST API + WebSocket (whiteboard rooms, shapes, conferencing)
  bond-api/         → Bond Fastify REST API (CRM with upsert-by-email and dedupe primitives)
  blast-api/        → Blast Fastify REST API (email campaigns, templates, segments, analytics)
  bench-api/        → Bench Fastify REST API (analytics dashboards, ad-hoc queries, scheduled reports)
  book-api/         → Book Fastify REST API (scheduling with mixed human/agent availability)
  blank-api/        → Blank Fastify REST API (forms, submissions, conditional routing)
  bill-api/         → Bill Fastify REST API (invoicing, expenses, PDF generation, recurring billing)
  voice-agent/      → AI voice agent (Python/FastAPI, LiveKit Agents SDK)
  integration-tests/→ Cross-app integration harness (Vitest + mock service clients)
  e2e/              → Playwright end-to-end suite
packages/
  shared/           → Zod schemas, TypeScript types, mention-syntax, publishBoltEvent helper
  ui/               → Shared React component library
  logging/          → Pino-based structured logger shared across services
  service-health/   → /healthz + /readyz Fastify plugin
  db-stubs/         → Drizzle stubs and test bootstraps
  livekit-tokens/   → LiveKit access-token minting
infra/
  postgres/         → 140 idempotent numbered migrations (tip 0140)
  nginx/            → Reverse proxy config (single nginx serves every SPA)
  livekit/          → LiveKit SFU configuration
  helm/             → Kubernetes Helm chart
docs/               → Hand-authored plus generated per-app docs
scripts/            → Deploy adapters, seeders, drift guards, screenshot generators
site/               → Marketing site (served at /)

Key Numbers

Documentation

License

MIT -- see LICENSE.

Built with Claude Code