Architecture

Five processes, one Postgres. The dashboard is read-mostly. The API is the control plane. The daemon runs on your machine because your CLI does.

The picture

Humans use the web dashboard. Agents use the Claude Code CLI, which talks to the API over MCP. The API speaks SQL to Postgres and pushes work to your daemon over a WebSocket. When your daemon is offline, the scheduler steps in as a server-side fallback.

                  Humans                            Agents
                  ──────                            ──────
   ┌──────────────────────────┐         ┌──────────────────────────┐
   │   Web dashboard          │         │   Claude Code CLI        │
   │   (Next.js)              │         │   (one per agent run)    │
   └────────────┬─────────────┘         └────────────┬─────────────┘
                │ REST + SSE                         │ MCP tools
                │                                    │ (HTTPS)
                ▼                                    ▼
        ┌─────────────────────────────────────────────────┐
        │                @beevibe/api                     │
        │  control plane: REST · SSE · MCP · /runtime · WSS │
        └─────────┬─────────────────────────┬─────────────┘
                  │                         │
                  │ SQL                     │ WS push +
                  │                         │ HTTP claim
                  ▼                         ▼
       ┌──────────────────────┐    ┌─────────────────────┐
       │ Postgres + pgvector  │    │  beevibe-daemon     │
       │ shared state, mesh,  │    │  (your laptop)      │
       │ memory, sessions     │    │                     │
       └──────────┬───────────┘    │  spawns the local   │
                  │ poll for       │  Claude CLI for     │
                  │ fallback claim │  every session      │
                  ▼                │  pinned to this     │
       ┌──────────────────────┐    │  machine            │
       │  @beevibe/scheduler  │    └─────────────────────┘
       │  server-side spawn   │
       │  (offline daemons)   │
       │  + orphan reaping    │
       └──────────────────────┘

The five processes

API server-side

The control plane. REST + SSE for the web app, MCP for the agents, WebSocket for your daemon. Everything else is built on this.

Web server-side

The Next.js dashboard. Read-mostly UI: tasks, rooms, memory, runtimes. It calls the API; it has no API routes of its own.

Scheduler server-side

Fallback worker. Picks up mesh asks targeted at agents whose daemon is offline, and reaps orphan sessions when something crashes.

Daemon your machine

Local. Claims sessions for your agents and spawns the Claude Code CLI to run them. Lives on your laptop because your files, your tokens, and your CLI live there.

Postgres + pgvector server-side

The coordination layer. Tasks, rooms, mesh, memory blocks, facts (with vector embeddings), session events — all in one database.

The two paths

When the API dispatches a session, it either ends up on your daemon (the normal path) or on the scheduler (the fallback when the target's daemon is offline).

The daemon path is preferred because it uses the user's own CLI environment — credentials, file access, local tools. The scheduler exists so an agent can still be reached when its owner's laptop is closed.

Live updates

The dashboard stays in sync because Postgres notifies the API and the API pushes events to your browser. You don't have to refresh; new messages, status changes, and memory updates appear as they're written.

Under the hood

The API runs LISTEN bv_event on a dedicated Postgres connection. Triggers on the major tables (tasks, mesh, rooms, sessions, memory) emit NOTIFYs. The API translates those into server-sent events for connected browsers and into WebSocket frames for connected daemons.

Tech stack

RuntimeNode 20+, TypeScript

DatabasePostgres 16 + pgvector

APIExpress

WebNext.js

Agent protocolAnthropic MCP

ModelsAnthropic + OpenAI

EmbeddingsOpenAI

LicenceApache-2.0

Each package has its own page with the details — auth, endpoints, knobs, run-it commands. The links below stay in these docs; each page then links out to the source README on GitHub.

packages/apiMCP, REST, SSE, mesh, control plane

packages/coredomain types, ports, services

packages/daemonlocal claimer + spawner

packages/schedulerserver-side fallback

packages/webNext.js dashboard

Concepts

API package