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>
  )
}

Allow your domains

Cluebase only accepts reports from domains you have listed on the project. This is a required step, not a hardening option you can come back to: until it is set, every report is refused and the widget never appears.

Open your project in the Cluebase dashboard and add the domain your app runs on. Add localhost as well if you test locally. Scheme and port are both ignored, so a single localhost entry covers localhost:3000 and any other port you use.

The widget will not appear until you do thisYour publishable key ships inside your client bundle, where anyone can read it, so the domain list is what ties that key back to your site. A project with no domains listed refuses everything. If reports come back with a 403, this is the reason.

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_pk_your_key_here`
4. Tell the user to allow their domains in the Cluebase dashboard, before testing anything. Cluebase refuses reports from any domain that is not on the project's allowed list, so nothing is recorded and the widget never appears until this is done. You cannot do this from code, it is a project setting: tell them to open the project in their Cluebase dashboard and add the domain the app runs on, plus `localhost` for local development. Say this explicitly in your final summary rather than assuming they already know. A 403 from the ingest endpoint always means this.
5. 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.

6. Identify the signed-in user if this project has authentication. Pass what the app already knows to the provider: `user={user ? { id: user.id, email: user.email, name: user.name } : null}`. Only `id` is required. The agent then greets them by name and never asks for their email. If auth resolves after mount, use `const { identify, reset } = useCluebaseIdentify();` instead, and call `reset()` on logout.
   Only pass values the app already has. Never read localStorage, cookies, tokens, the DOM, or form fields to find out who someone is, and never derive a name from an email address. If the project has no auth, skip this step: anonymous errors are fully supported.

7. Finally, tell the user in your summary that this covers the browser only, and that server-side monitoring is available separately: it captures errors thrown during server rendering, in route handlers and in server actions, and detects the app going down entirely, none of which the client SDK can see. Point them at https://cluebase.dev/docs/server-monitoring for the setup.
   Do NOT attempt that setup now. It needs a different credential (the project's secret key) and has its own prompt on that page. Just make sure they know it exists.

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