Debugger Panel

A powerful development tool that provides real-time insights into your Cedar OS application with network monitoring, message tracking, and state inspection

The DebuggerPanel is an essential development component that gives you comprehensive visibility into your Cedar OS application’s runtime behavior. It provides real-time monitoring of network requests, message flows, and application state changes.

The DebuggerPanel should only be used during development and should not be included in production builds.

Overview

The DebuggerPanel appears as a draggable, floating panel with three main tabs:

• Network: Monitor agent connection logs and API requests
• Messages: Track chat messages and their metadata
• States: Inspect registered Cedar OS states in real-time

Cedar Debugger Panel in action - real-time monitoring of network requests, messages, and application state

Features

🔍 Real-time Monitoring

• Live tracking of network requests and responses
• Message flow visualization
• State change detection and inspection

🎯 Interactive Interface

• Collapsible floating button that expands to full panel
• Draggable positioning anywhere on screen
• Resizable panel with corner and edge handles
• Copy-to-clipboard functionality for debugging data

📊 Comprehensive Tabs

• Network Tab: View agent connection logs, request/response data, and timing information
• Messages Tab: Inspect chat messages, metadata, and message history
• States Tab: Monitor all registered Cedar OS states and their current values

⚡ Development Controls

• Pause/resume debugging to control data collection
• Clear all logs with a single click
• Visual indicators showing data counts in each tab

Basic Usage

Installation

The DebuggerPanel is available as part of the cedar-os-components package:

React Component

import { DebuggerPanel } from 'cedar-os-components';

export default function App() {
  return (
    <div className="relative h-screen">
      {/* Your app content */}
      <YourMainContent />
      
      {/* Add DebuggerPanel for development */}
      <DebuggerPanel />
    </div>
  );
}

Environment-based Inclusion

For production safety, conditionally render the DebuggerPanel:

import { DebuggerPanel } from 'cedar-os-components';

export default function App() {
	return (
		<div className='relative h-screen'>
			<YourMainContent />

			{/* Only show in development */}
			{process.env.NODE_ENV === 'development' && <DebuggerPanel />}
		</div>
	);
}

Component API

Props

initialPosition · { x: number; y: number } · default: "{ x: window.innerWidth - 80, y: 20 }"

Initial position of the debugger panel on the screen. The panel will appear at these coordinates when first rendered.

className · string · default: ""

Optional CSS class name to apply custom styling to the debugger panel.

Default Behavior

• Initial State: Appears as a collapsed floating button in the top-right corner
• Positioning: Automatically constrains to viewport boundaries when dragged
• Sizing: Default panel size is 500x350px with minimum size constraints
• Data Collection: Starts collecting data immediately when rendered

Using the Debugger

Collapsed State

When collapsed, the DebuggerPanel shows as a floating bug icon button:

• Red badge: Indicates the number of network logs when present
• Click to expand: Opens the full debugging interface
• Drag to move: Reposition the button anywhere on screen

Expanded State

The expanded panel provides full debugging capabilities:

1. Network Tab

   Monitor all agent connections and API requests:

   • View request/response data
   • Check timing information
   • Copy request details for external testing
   • Filter by request type or status
2. Messages Tab

   Track chat message flow: - Inspect message content and metadata - View message timestamps - Copy message data for analysis - Monitor message processing states

3. States Tab

   Examine application state:

   • View all registered Cedar OS states
   • Monitor real-time state changes
   • Copy state data for debugging
   • Track state update frequency

Panel Controls

The debugger panel header includes several control buttons:

• Refresh: Toggle debugging on/off (green when active)
• Trash: Clear all collected logs and data
• X: Collapse the panel back to button state

Advanced Usage

Custom Positioning Strategy

For complex layouts, you might want to position the debugger relative to other UI elements:

import { DebuggerPanel } from 'cedar-os-components';
import { useEffect, useState } from 'react';

export default function App() {
	const [debuggerPosition, setDebuggerPosition] = useState({ x: 0, y: 0 });

	useEffect(() => {
		// Position relative to a specific element
		const sidebar = document.getElementById('sidebar');
		if (sidebar) {
			const rect = sidebar.getBoundingClientRect();
			setDebuggerPosition({
				x: rect.right + 20,
				y: rect.top,
			});
		}
	}, []);

	return (
		<div className='relative h-screen'>
			<YourMainContent />
			<DebuggerPanel initialPosition={debuggerPosition} />
		</div>
	);
}

Integration with Cedar Store

The DebuggerPanel automatically connects to your Cedar store and monitors:

• Agent connection logs via store.agentConnectionLogs
• Chat messages via store.messages
• Debug state via store.isDebugEnabled
• Registered states via store.registeredStates

Make sure your Cedar store is properly configured before adding the DebuggerPanel, as it depends on these store properties for functionality.

Development Workflow

Here’s a recommended workflow for using the DebuggerPanel:

Initial Setup

1. Add DebuggerPanel to your main app component
2. Ensure it’s conditionally rendered for development only
3. Test that it appears and can be positioned as needed

Best Practices

Development Environment

Always conditionally render based on environment variables

Position the panel where it won’t interfere with your main UI

Clear logs regularly during long debugging sessions

Performance Considerations

The DebuggerPanel collects data continuously, which can impact performance during extended debugging sessions. Use the pause/resume toggle when not actively debugging.

Data Security

Never include the DebuggerPanel in production builds as it exposes internal application data and could pose security risks.

Troubleshooting

DebuggerPanel not appearing

• Verify that cedar-os-components is properly installed
• Check that the component is rendered within a Cedar store provider
• Ensure the initial position is within viewport boundaries
• Confirm the component isn’t hidden by CSS z-index issues

No data showing in tabs

• Verify your Cedar store is properly configured - Check that debugging is enabled (green refresh button) - Ensure your agent connections are properly set up - Try clearing logs and generating new activity

Panel positioning issues

• The panel auto-constrains to viewport boundaries
• Try setting a custom initialPosition prop
• Check for CSS conflicts that might affect positioning
• Ensure the parent container allows absolute positioning

Related Components

• CommandBar - For command-based debugging
• ChatInput - For interactive debugging sessions
• FloatingContainer - For custom floating UI elements