Supabase Realtime for AI Agent Dashboards

Why Polling Kills AI Agent Dashboards

When you build an AI agent system, you need visibility into what's happening right now. Claude processes tasks, makes decisions, and your dashboard needs to reflect that in real-time. Polling every 2–5 seconds creates lag, wastes database queries, and makes the interface feel stale.

Supabase Realtime solves this with WebSocket subscriptions. Instead of asking your database 'has anything changed?', you listen for changes as they happen. Your dashboard updates within milliseconds, not seconds. For agent systems, this means seeing task completions, token consumption, and decision branches the moment they occur.

Setting Up Realtime Subscriptions for Agent Events

Create a simple agent_events table and subscribe to changes in your Next.js dashboard component. Supabase broadcast channels work perfectly for high-frequency updates—token counts, status changes, and reasoning traces.

Here's how to listen for agent task completions:

import { useEffect, useState } from 'react';
import { createClient } from '@supabase/supabase-js';

const supabase = createClient(url, key);

export function AgentDashboard() {
  const [tasks, setTasks] = useState([]);

  useEffect(() => {
    const subscription = supabase
      .channel('agent-events')
      .on(
        'postgres_changes',
        { event: '*', schema: 'public', table: 'agent_tasks' },
        (payload) => {
          setTasks((prev) => [...prev, payload.new]);
        }
      )
      .subscribe();

    return () => subscription.unsubscribe();
  }, []);

  return <div>{tasks.map(t => <TaskCard key={t.id} task={t} />)}</div>;
}

Structuring Your Agent Event Schema

Your agent_events table should track the full lifecycle: task creation, Claude's reasoning steps, tool calls, results, and completion. Include timestamps, token counts, and the agent's trace for debugging.

A minimal schema includes id, agent_id, task_id, event_type ('reasoning' | 'tool_call' | 'complete'), payload (JSON), tokens_used, and created_at. This gives your dashboard everything needed to show live progress bars, token budgets, and decision trees.

Broadcasting Agent State Without Database Writes

For ultra-high-frequency updates (token counts changing every millisecond), skip the database and use Supabase broadcast channels. Send updates from your Claude-running backend directly to the dashboard via WebSocket.

This keeps your database write load low while keeping the UI perfectly in sync. Use broadcast for live metrics, reserve database inserts for immutable audit trails.

Handling Backpressure and Connection Recovery

Realtime subscriptions can drop. Always implement reconnection logic and debounce rapid updates if your agent fires thousands of events per minute. Supabase clients handle reconnection automatically, but wrap your subscription handler to gracefully handle stale data.

Cache the last known state client-side so your dashboard doesn't blank out during a reconnect. For mission-critical dashboards, maintain a fallback polling strategy at 10–30 second intervals.

Open-Source Implementation

The Pantheon project (github.com/lewisallena17/pantheon) is a production-ready example of Supabase Realtime integrated with Claude-powered agents. It demonstrates the full stack: agent task orchestration, Realtime event streaming, and a Next.js dashboard that updates sub-second.

Fork it to see how to structure your agent_events table, implement Realtime subscriptions, and build live task traces. The repo includes retry logic, error boundaries, and performance-tuned database indexes.

Open-source implementation

Everything in this article runs in pantheon — a production-ready Next.js + Supabase + Claude starter. Clone it, deploy to Vercel, run PM2. The dashboard auto-commits every agent edit and reverts itself if TypeScript breaks.