agent-ui-overlay

AI Agent UI overlay for dynamic configuration via MCP tools.

A React component library that provides a beautiful, draggable overlay interface for AI agents powered by Claude and MCP (Model Context Protocol).

Features

• Draggable & resizable overlay window
• Real-time chat interface with AI agent
• Activity log with progressive disclosure (summary/details/full)
• Configuration preview with change tracking
• Dark and light themes
• Multiple adapter options (Firestore real-time, REST polling)
• TypeScript support
• Zero runtime dependencies (only peer deps: React, Zustand, Framer Motion)

Installation

npm install agent-ui-overlay
# or
yarn add agent-ui-overlay
# or
pnpm add agent-ui-overlay

Peer Dependencies

npm install react react-dom zustand framer-motion

Quick Start

import { AgentOverlay, RestAdapter } from 'agent-ui-overlay';
import 'agent-ui-overlay/styles';

function App() {
  const adapter = new RestAdapter({
    baseUrl: '/api/agent',
  });

  return (
    <AgentOverlay
      adapter={adapter}
      sessionConfig={{
        partnerId: 'partner123',
        context: { dynamicAdId: 'ad456' }
      }}
      onConfigChange={(config) => {
        console.log('Agent updated config:', config);
      }}
      theme="dark"
      position="bottom-right"
      resizable
      minimizable
    />
  );
}

Using with Firebase/Firestore

import { AgentOverlay, FirestoreAdapter } from 'agent-ui-overlay';
import { getFirestore } from 'firebase/firestore';

const firestore = getFirestore();

function App() {
  const adapter = new FirestoreAdapter({
    firestore,
    agentEndpoint: '/api/agent/chat',
  });

  return (
    <AgentOverlay
      adapter={adapter}
      sessionConfig={{
        partnerId: 'partner123',
      }}
      theme="dark"
    />
  );
}

Components

AgentOverlay

Main overlay component with tabs for Chat, Activity, and Config.

<AgentOverlay
  adapter={adapter}              // Required: AgentAdapter instance
  sessionConfig={{               // Required: Session configuration
    partnerId: string;
    userId?: string;
    context?: Record<string, unknown>;
  }}
  onConfigChange={(config) => {}} // Called when agent makes config changes
  onSessionEnd={(session) => {}}  // Called when session ends
  theme="dark"                    // 'light' | 'dark' | 'system'
  position="bottom-right"         // Initial position
  defaultSize={{ width: 420, height: 600 }}
  resizable                       // Allow resizing
  minimizable                     // Allow minimizing to bubble
  closable                        // Allow closing
  zIndex={10000}                  // Custom z-index
  className=""                    // Custom class name
/>

AgentChat

Standalone chat component.

<AgentChat
  adapter={adapter}
  placeholder="Ask the AI agent..."
  showToolCalls      // Show tool call details inline
  showThinking       // Show thinking indicator
/>

ActivityLog

Standalone activity log component with progressive disclosure.

<ActivityLog
  adapter={adapter}
  defaultDisplayLevel="summary"  // 'summary' | 'details' | 'full'
  autoScroll                     // Auto-scroll to new entries
  maxEntries={100}               // Max entries to display
/>

ConfigPreview

Configuration preview with change tracking.

<ConfigPreview
  config={currentConfig}
  changes={[
    { path: 'template.title', oldValue: 'Old', newValue: 'New', timestamp: new Date() }
  ]}
  format="json"  // 'json' | 'visual'
/>

Hooks

useAgentSession

Manage agent session lifecycle.

const {
  session,      // Current session
  messages,     // Chat messages
  activityLog,  // Activity log entries
  isLoading,    // Loading state
  error,        // Error message
  sendMessage,  // Send a message
  endSession,   // End the session
} = useAgentSession({
  adapter,
  sessionConfig,
  onConfigChange,
  onSessionEnd,
});

useActivityLog

Manage activity log state.

const {
  entries,          // Filtered entries
  displayLevel,     // Current display level
  setDisplayLevel,  // Change display level
  filterByType,     // Filter by entry type
  typeCounts,       // Count by type
  clearLog,         // Clear all entries
} = useActivityLog({ maxEntries: 100 });

Adapters

RestAdapter

Uses REST API with polling for updates.

const adapter = new RestAdapter({
  baseUrl: '/api/agent',
  pollInterval: 1000,           // Polling interval (ms)
  headers: { 'X-Api-Key': '...' },  // Custom headers
});

FirestoreAdapter

Uses Firestore for real-time updates.

const adapter = new FirestoreAdapter({
  firestore,                    // Firestore instance
  agentEndpoint: '/api/agent',  // Backend endpoint for sending messages
});

Custom Adapter

Implement the AgentAdapter interface:

interface AgentAdapter {
  init(config: SessionConfig): Promise<void>;
  sendMessage(message: string): Promise<void>;
  onMessage(callback: (message: ChatMessage) => void): () => void;
  onActivityLog(callback: (entries: ActivityLogEntry[]) => void): () => void;
  onSessionChange(callback: (session: AgentSession | null) => void): () => void;
  onConfigChange?(callback: (config: Record<string, unknown>) => void): () => void;
  getSession(): AgentSession | null;
  endSession(): Promise<void>;
  destroy(): void;
}

Theming

Override CSS custom properties to customize the look:

.ai-ui-theme-dark {
  --ai-ui-bg: #1a1a1a;
  --ai-ui-accent: #6366f1;
  --ai-ui-text: #fff;
  /* ... see overlay.css for all variables */
}

License

MIT - Reko Labs