How it works

Claudium is three processes connected by WebSockets.

   ┌───────────────┐        ┌───────────────┐        ┌───────────────┐
   │   Watcher /   │  WS    │      Hub      │  WS    │    Viewer     │
   │    Sender     │──────▶│ (Node + Postgres)│──────▶│  (browser UI) │
   │  (per device) │        │   one per org   │        │ (any device)  │
   └───────────────┘        └───────────────┘        └───────────────┘
        │                          │                          │
        │ tails .jsonl             │ persists to events       │ renders brain
        │ Claude Code              │ stitches into turns      │ shows agents
        │ session logs             │ embeds via OpenAI        │ shows regions
        │                          │ → turn_embeddings        │
        ▼                          ▼                          ▼
   tool_use JSON           pgvector + RLS               live visualization

Watcher (sender)

A small Node process on each contributor's machine. It tails .jsonl files under ~/.claude/projects/ using chokidar, parses each new assistant message for tool_use blocks, and forwards a compact event over WebSocket.

You can replace the watcher entirely if your agent runtime isn't Claude Code. See sender integration for the wire format.

Hub

The Node server that fans events from senders to viewers. Single-instance per org. Responsibilities:

• Auth — sender tokens (SHA-256-hashed in the DB), viewer sessions (signed cookie or DB-backed, picked by env flag).
• Validate — drops events with unknown regions, oversized strings, or invalid token counts.
• Broadcast — pushes each accepted event to every connected viewer in real time.
• Persist — writes events to events, asynchronously groups them into turns with summaries, and embeds those summaries into turn_embeddings.
• Enforce quota — gates persistence on the org's monthly cap (Free 10k, Team 100k/seat).
• Bill — Stripe Checkout for upgrades, webhook for subscription state.

The whole codebase is in claude-brain-watcher/ — about 4k lines of Node, mostly hub.js and a handful of lib/*.js modules.

Viewer

A static page (landing/) served by the hub. Connects to the hub's /ws endpoint with the session cookie, receives events, drives the brain visualization. Three viewing modes:

• Live — events fire as they arrive. Default.
• Brain Scan — accumulating intensity over the last N minutes.
• Ping Pong — sender → region → sender, showing the social pattern of who's working on what.

All modes are pure browser code — no server round-trips after the initial WebSocket connection. Latency from tool call to visible firing is ~50–150 ms over the open internet.

Data model

The persistent state lives in seven Postgres tables, all org_id-partitioned with RLS enforcement:

• orgs, users, memberships — the multi-tenant foundation.
• senders — one per contributor token. Hash, not plaintext.
• events — one row per tool call. High-volume.
• turns — derived grouping. The unit the embedding pipeline operates on.
• turn_embeddings — 1536-dim vectors via OpenAI's text-embedding-3-small, indexed with HNSW for nearest-neighbour queries.
• subscriptions — Stripe state per org.

Plus three auxiliary tables: sessions (DB-backed sessions, optional), signup_leads (the public lead form), audit_events (append-only audit log).

What's deliberately NOT in scope

A few things Claudium will not be:

• A general-purpose APM. We're not Datadog. The brain is the product; metrics dashboards are not on the roadmap.
• A model trainer. Your data never leaves your org. We don't fine-tune across customers, even with explicit consent.
• A code repository. We never persist file contents, prompts, or model outputs. Metadata only.

If those are what you need, you're on the wrong site.