Debug Mode

Debug mode adds a Tools tab to the edge trigger, giving you a dedicated interface for testing tool execution during development.

Enabling Debug Mode

Pass debug: true in your SDK configuration.

examples/guides/debug-mode/enable-debug.tsx

import { PillarProvider } from '@pillar-ai/react';

function App() {
  return (
    <PillarProvider
      productKey="your-product-key"
      config={{
        debug: process.env.NODE_ENV === 'development',
      }}
    >
      {children}
    </PillarProvider>
  );
}

Best Practice: Development Only

Always gate debug mode behind an environment check to prevent it from appearing in production:

tsx

config={{
  debug: process.env.NODE_ENV === 'development',
}}

This ensures the Tools tab only appears during local development.

Using the Tools Tab

When debug mode is enabled, a wrench icon appears in the edge trigger. Click it to open the Tool Debugger.

Features

Feature	Description
Search	Filter tools by name, description, or type
Tool List	Browse all registered tools with their type badges
Tool Details	View description, input schema, and handler status
JSON Editor	Edit input parameters with real-time validation
Execute	Run the tool and see results or errors

Tool Information

For each tool, the debugger shows:

Name - The tool identifier
Type - Badge indicating navigate, query, trigger_tool, etc.
Description - What the tool does
Source - How the tool was registered (see below)
Handler - Whether an executable handler exists

Input Schema

If a tool defines an inputSchema, the debugger displays it and pre-populates the JSON editor with default values. Edit the JSON to test different parameter combinations.

Execution Results

After clicking Execute Tool, results appear below:

Success - Green box with the returned data (JSON formatted)
Error - Red box with the error message

Tool Sources

The debugger shows where each tool was registered:

Source	Registration Method	Handler
`defineTool`	`pillar.defineTool()` or `usePillarTool()`	Included
`registerTool`	`pillar.registerTool()` (deprecated)	Via `onTask()`
`onTask`	Synced via CLI, handled by `pillar.onTask()`	Via `onTask()`

Tools registered with defineTool include their handler directly and can be executed from the debugger. Tools from other sources require a matching onTask() handler to be executable.

Reactive Updates

The tool list updates automatically when tools are added or removed. This is useful when:

Navigating between pages that register page-specific tools
Tools are conditionally registered based on user context
Testing the cleanup behavior of defineTool's unsubscribe function

If a tool you're viewing gets removed (e.g., by navigating away from the page that defined it), the selection clears automatically.

Debugging Workflow

Find your tool - Use search to filter by name or description
Check the schema - Verify the input parameters match your expectations
Test execution - Edit the JSON input and click Execute
Verify results - Check the returned data or error message
Iterate - Adjust your tool definition and test again

Next Steps

Setting Up Tools - Learn how to define tools
Testing - Write tests for your tool handlers
Context - Use context to filter which tools appear

Search documentation