Search documentation

Search documentation

Customize your docs experience — choose your preferred framework for code examples:

Quickstart

Add an AI co-pilot to your app that can answer questions and take actions. By the end of this guide you'll have a working panel with your first tool synced.

Prerequisites

  • React 17+ (this guide uses Next.js examples, but works with Vite, CRA, etc.)

Step 1: Install the SDK

bash
npm install @pillar-ai/react

Create a client component wrapper since PillarProvider uses React context:

providers/PillarSDKProvider.tsx
'use client';


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


export function PillarSDKProvider({ children }: { children: React.ReactNode }) {
  return (
    <PillarProvider productKey="your-product-key">
      {children}
    </PillarProvider>
  );
}

Then wrap your app in the root layout:

examples/quickstarts/react/layout-provider.tsx
// app/layout.tsx
import { PillarSDKProvider } from '@/providers/PillarSDKProvider';


export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <PillarSDKProvider>
          {children} {/* Your page content renders here */}
        </PillarSDKProvider>
      </body>
    </html>
  );
}

Layout tip: In push mode, Pillar adds padding to the html element to make room for the panel. If your layout has an element with width: 100vw, set panel.pushTarget to that element's selector (e.g., '#__next', 'main') to prevent horizontal overflow.

Step 2: Create a Tool

Tools let the AI assistant perform tasks in your app — navigating to a page, opening a modal, calling an API. Without tools, the co-pilot can only answer questions. With tools, it becomes an assistant that does things.

examples/quickstarts/react/first-tool.tsx
import { usePillarTool } from '@pillar-ai/react';
import { useRouter } from 'next/navigation';


export function usePillarTools() {
  const router = useRouter();


  usePillarTool({
    name: 'open_settings',
    type: 'navigate', // navigate | trigger_tool | query | external_link | copy_text
                      // Full reference: https://trypillar.com/docs/guides/tools
    description: 'Navigate to the settings page',
    examples: ['open settings', 'go to settings'],
    autoRun: true,
    execute: () => router.push('/settings'),
  });
}


// Call usePillarTools() inside PillarProvider (e.g. in app/layout.tsx)

Call the hook from a component inside your PillarProvider:

tsx
import { usePillarTools } from '@/hooks/usePillarTools';


function App() {
  usePillarTools();
  return <div>{/* your app */}</div>;
}

Step 3: Sync

The pillar-sync CLI scans your code for tool definitions and registers them with Pillar's backend so the AI can discover them.

Run manually:

examples/quickstarts/sync-tools.sh
PILLAR_SLUG=your-product-slug PILLAR_SECRET=your-secret-token npx pillar-sync --scan ./src

Replace the slug and secret placeholders with the values from your dashboard. Point --scan at the directory containing your tool definitions.

Run in CI/CD:

bash
npx pillar-sync --scan ./src

Set PILLAR_SLUG and PILLAR_SECRET as environment variables in your CI provider. See Syncing Tools for GitHub Actions and GitLab CI examples.

Step 4: Test it

  1. Start your dev server: npm run dev
  1. Click the sidebar tab on the screen edge to open the panel
  2. Try asking: "go to settings"
  3. The co-pilot should suggest your open_settings tool — navigate tools auto-run by default when they are the top match, so it may execute immediately

Next steps