cluebase

Get Started

Cluebase is an agentic rescue widget for the moment your app breaks.

When an error hits one of your users, Cluebase catches it and opens a live conversation with that specific person (calm, honest, and useful) instead of leaving them stuck on a broken page or a blank crash screen. The agent finds out what they were doing, gets their contact info so your team can follow up, and hands you a structured incident with the full transcript.

Cluebase doesn't explain errors to developers. It talks to the person who actually hit the error, and your team gets a Slack or Telegram alert once the conversation closes.

Who it's for

Any product with real users who can hit real errors (a SaaS dashboard, a checkout flow, or an onboarding wizard) where a crash currently just shows a stack trace (or nothing at all) to someone who was trying to get something done.

You need to:

  • Stop losing users silently when something breaks, as most never file a support ticket and just leave
  • Know what someone was actually doing when an error fired, not just the stack trace
  • Get a way to follow up with the affected person, not just a log entry nobody reads

Cluebase does all three. You add one package and the rescue conversation happens automatically.

What you get

The rescue conversation

A side-panel widget that opens the moment an error is caught, streams a real, non-scripted reply from the agent, and asks one thing at a time: what they were doing, then (only once trust is established) how to reach them. Light/dark themed to match the host page automatically.

The incident dashboard

Every conversation is logged with its full transcript, an outcome (saved / at risk / lost), and the technical detail (error, stack, route, browser) collapsed underneath. Errors are deduplicated into groups by fingerprint, so twelve users hitting the same bug show up as one error group with twelve individual incidents, not twelve unrelated rows.

How it works

Install the SDK, wrap your application root with CluebaseProvider, and pass your API key. The provider installs a global error boundary and starts a module-level window.onerror/unhandledrejection listener, registered at import time (not inside a React effect), so it still fires even if the crash happens during hydration, before your app has fully mounted.

Terminal
npm install cluebase-next
app/layout.tsx
import { CluebaseProvider } from 'cluebase-next'
export default function RootLayout({ children }) {
  return (
    <CluebaseProvider apiKey={process.env.NEXT_PUBLIC_CLUEBASE_API_KEY}>
      {children}
    </CluebaseProvider>
  )
}

Try it

Add a test trigger to any component to verify the integration works. The error boundary catches the exception and the Cluebase dashboard shows the event within seconds.

components/TestButton.tsx
import { useCluebaseReport } from 'cluebase-next'
export function TestButton() {
  const { reportError } = useCluebaseReport()
  return (
    <button onClick={() => reportError(new Error('Test Cluebase!'))}>
      Trigger test error
    </button>
  )
}
ImportantDo not use throw inside onClick handlers. React event handlers swallow thrown errors before they reach the error boundary. Use reportError instead.

Next steps

Ready to integrate? Pick your framework guide:

Coding Agent Quick Integration Prompts

Select your stack and copy the 1-click prompt to let Cursor, Claude, ChatGPT, Copilot, or Antigravity integrate Cluebase into your repository.

Integrate Cluebase error tracking into this Next.js project by following these steps:
1. Install cluebase-next: `npm install cluebase-next` (or `pnpm add cluebase-next`)
2. Wrap your app root with `CluebaseProvider`:
   - App Router (`app/layout.tsx`): Import `{ CluebaseProvider }` from 'cluebase-next' and wrap `{children}` inside `<body>`: `<CluebaseProvider apiKey={process.env.NEXT_PUBLIC_CLUEBASE_API_KEY ?? ''}>`
   - Pages Router (`pages/_app.tsx`): Import `{ CluebaseProvider }` from 'cluebase-next' and wrap `<Component {...pageProps} />`
3. Add API key to `.env.local`: `NEXT_PUBLIC_CLUEBASE_API_KEY=cb_your_api_key_here`
4. Add a test trigger button. Import `{ useCluebaseReport }` from 'cluebase-next', call `const { reportError } = useCluebaseReport();` inside your component, then add: `<button onClick={() => reportError(new Error('Test Cluebase!'))}>Trigger Error</button>`
   Important: Do NOT use `throw` inside onClick: React event handlers swallow thrown errors before they reach the error boundary.

Note: If you have web search capability, visit https://cluebase.dev/docs for detailed documentation and API reference.
NextNext.js setup