GuideKit

AI-powered user guidance SDK that understands your website and guides users through it — like a human sitting beside them.

Getting Started · Documentation · GitHub · Architecture · Quick Start

---

Why GuideKit?

Existing solutions fall short:

• Voice SDKs (Vapi, ElevenLabs, LiveKit) — great voice, zero DOM awareness
• Browser AI agents (Browser-Use, Stagehand) — server-side automation, not embeddable
• Support widgets (Intercom, Zendesk) — scripted flows, no real understanding

GuideKit combines all three: an embeddable SDK where the AI agent sees your page, understands its structure, and guides users with voice, text, and visual cues — spotlights, tooltips, scrolling, and navigation.

Features

• DOM Intelligence — Auto-discovers site structure, content, navigation, forms, and overlays
• Text + Voice — Full conversation via text or voice (Deepgram, ElevenLabs, or Web Speech API)
• Visual Guidance — Spotlight overlay, tooltips, smooth scrolling, guided tours
• LLM Tool Calling — highlight, scroll, navigate, click, and custom developer actions
• User Awareness — Viewport tracking, dwell/idle detection, rage click detection
• Proactive Triggers — Context-aware suggestions with progressive cooldowns
• Token-Based Auth — API keys never reach the browser
• React + Vanilla — First-class React hooks or plain <script> tag
• Accessible — WCAG 2.1 AA, keyboard navigation, screen reader support
• Lightweight — Core ~65 KB gz, React ~8 KB gz, tree-shakeable

Packages

Package	Version	Role	Audience	Status
@guidekit/core	1.0.0	DOM intelligence, orchestration, context, rendering primitives	Every app integration	Core
@guidekit/react	1.0.0	Provider, hooks, Shadow DOM widget	React / Next.js apps	Core
@guidekit/server	1.0.0	Token generation, auth middleware, session helpers	Server runtimes backing GuideKit clients	Core
@guidekit/vanilla	1.0.0	Script-tag and framework-agnostic browser integration	Non-React apps and simple embeds	Stable optional
@guidekit/vad	0.1.1	Voice activity detection model and helpers	Voice-enabled experiences	Optional voice
@guidekit/cli	1.0.0	init, doctor, generate-secret	Local setup, contributor diagnostics, CI parity checks	Optional DX
@guidekit/intelligence	1.0.0	Semantic page intelligence engine	Advanced understanding and ranking pipelines	Advanced optional
@guidekit/knowledge	1.0.0	Knowledge retrieval with BM25 / TF-IDF search	Retrieval-augmented guidance	Advanced optional
@guidekit/plugins	1.0.0	Plugin system and extension hooks	Custom platform extensions and partner integrations	Advanced optional

Version numbers do not move in lockstep. Tier A packages (core, react, server, vanilla) ship together on breaking changes. Tier B optional packages evolve on their own cadence with a peer dependency on @guidekit/core@^1.0.0.

Quick Start

Install

npm install @guidekit/react @guidekit/server

1. Generate a signing secret

npx @guidekit/cli generate-secret

Add it to .env.local:

GUIDEKIT_SECRET=your-generated-secret
LLM_API_KEY=your-llm-api-key

2. Create server routes (Next.js App Router)

// app/api/guidekit/token/route.ts
import { createNextAppRouterRoutes } from '@guidekit/server/next';

const routes = createNextAppRouterRoutes({
  signingSecret: process.env.GUIDEKIT_SECRET!,
  createTokenOptions: () => ({
    llmApiKey: process.env.LLM_API_KEY!,
    expiresIn: '15m',
    allowedOrigins: ['https://yourapp.com'],
  }),
});

export const POST = routes.POST_token;

// app/api/guidekit/llm/route.ts
import { createNextAppRouterRoutes } from '@guidekit/server/next';

const routes = createNextAppRouterRoutes({
  signingSecret: process.env.GUIDEKIT_SECRET!,
});

export const POST = routes.POST_llm;

3. Wrap your app in the Provider (proxy mode — no client API keys)

// app/providers.tsx
'use client';

import { GuideKitProvider } from '@guidekit/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <GuideKitProvider
      tokenEndpoint="/api/guidekit/token"
      proxy={{ llm: '/api/guidekit/llm', health: '/api/guidekit/health' }}
      llm={{ provider: 'gemini', model: 'gemini-2.5-flash' }}
      agent={{ name: 'Guide', greeting: 'Hi! How can I help you today?' }}
      options={{ mode: 'text', debug: process.env.NODE_ENV === 'development' }}
    >
      {children}
    </GuideKitProvider>
  );
}

// app/layout.tsx
import { Providers } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html><body>
      <Providers>{children}</Providers>
    </body></html>
  );
}

4. Verify your setup

npx @guidekit/cli doctor

That's it. A chat widget appears on your site. The agent auto-discovers your pages and can answer questions, spotlight elements, navigate users, and execute custom actions.

React Hooks

GuideKit provides focused hooks that minimize re-renders:

import {
  useGuideKitStatus,
  useGuideKitVoice,
  useGuideKitActions,
  useGuideKitContext,
} from '@guidekit/react';

function MyComponent() {
  // Status — re-renders only on status changes
  const { isReady, agentState, error } = useGuideKitStatus();

  // Voice — re-renders only on voice state changes
  const { isListening, isSpeaking, startListening, stopListening, sendText } = useGuideKitVoice();

  // Actions — never re-renders (stable refs)
  const { highlight, dismissHighlight, scrollToSection, startTour } = useGuideKitActions();

  // Context — never re-renders (stable refs)
  const { setPageContext, registerAction } = useGuideKitContext();
}

Custom Actions

Register domain-specific actions the AI can invoke:

const { registerAction } = useGuideKitContext();

registerAction('addToCart', {
  description: 'Add a product to the shopping cart',
  parameters: { productId: 'string', quantity: 'number' },
  handler: async ({ productId, quantity }) => {
    await cart.add(productId, quantity);
    return { success: true, message: `Added ${quantity} item(s)` };
  },
});

// The AI can now say: "I've added that to your cart!"
// while executing the action behind the scenes.

Content Map (Prevent Hallucination)

Provide ground-truth content the AI references instead of guessing:

<GuideKitProvider
  contentMap={{
    'section-pricing': {
      description: 'Pricing starts at $29/mo for the Starter plan',
      facts: ['14-day free trial', 'No credit card required'],
    },
  }}
>

Or use a dynamic function for runtime data:

<GuideKitProvider
  contentMap={(sectionId) => {
    if (sectionId === 'section-inventory') {
      return { description: `${inventory.count} items in stock` };
    }
    return null;
  }}
>

Vanilla JS (Non-React)

Use GuideKit with a script tag — no build tools required:

<script src="https://cdn.jsdelivr.net/npm/@guidekit/vanilla/dist/index.global.js"></script>
<script>
  GuideKit.init({
    tokenEndpoint: '/api/guidekit/token',
    agent: { name: 'Guide', greeting: 'Hello!' },
  });
</script>

Or via npm:

import { init, sendText, highlight, destroy } from '@guidekit/vanilla';

await init({ tokenEndpoint: '/api/guidekit/token' });
const response = await sendText('What is this page about?');

Voice Mode

Enable voice with STT/TTS providers:

<GuideKitProvider
  tokenEndpoint="/api/guidekit/token"
  options={{ mode: 'voice' }}
>

Server-side, add provider keys:

const token = await createSessionToken({
  signingSecret: process.env.GUIDEKIT_SECRET!,
  llmApiKey: process.env.LLM_API_KEY!,
  sttApiKey: process.env.STT_API_KEY!,
  ttsApiKey: process.env.TTS_API_KEY!,
  expiresIn: '15m',
});

Install the VAD package for voice activity detection:

npm install @guidekit/vad

Voice features include:

• Half-duplex (no echo issues) with barge-in support
• Automatic degradation to text-only if voice fails
• Real-time captions always displayed
• Browser autoplay policy compliance (no auto-play audio)

DevTools & Testing

// Development only — pipeline inspector, latency waterfall, section viewer
import { GuideKitDevTools } from '@guidekit/react/devtools';

{process.env.NODE_ENV === 'development' && <GuideKitDevTools />}

// Testing — mock provider for unit tests
import { MockGuideKitProvider, simulateVoiceInput } from '@guidekit/react/testing';

<MockGuideKitProvider initialState={{ isReady: true }}>
  <ComponentUnderTest />
</MockGuideKitProvider>

Security

• API keys never reach the browser — stored server-side, accessed via short-lived JWT tokens
• Token refresh — automatic at 80% TTL with multi-tab coordination
• Click safety — default deny-list blocks submit/reset/form clicks by LLM
• Privacy hooks — onBeforeLLMCall for custom PII scrubbing
• DOM exclusion — data-guidekit-ignore attribute skips sensitive subtrees
• XSS prevention — all tooltip content rendered via textContent, never innerHTML
• Input validation — configurable maxMessageLength (default 10,000 chars)
• Concurrent request guard — prevents double-submission

Architecture

┌─────────────────────────────────────────────────────────┐
│                    @guidekit/react                       │
│              Provider · Hooks · Widget (Shadow DOM)      │
├─────────────────────────────────────────────────────────┤
│                    @guidekit/core                        │
│  ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌───────────┐ │
│  │   DOM    │ │ Context  │ │    LLM    │ │  Visual   │ │
│  │ Scanner  │ │ Manager  │ │Orchestrator│ │ Guidance  │ │
│  └──────────┘ └──────────┘ └───────────┘ └───────────┘ │
│  ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌───────────┐ │
│  │  Voice   │ │Awareness │ │Navigation │ │ EventBus  │ │
│  │ Pipeline │ │  System  │ │Controller │ │& Resources│ │
│  └──────────┘ └──────────┘ └───────────┘ └───────────┘ │
├─────────────────────────────────────────────────────────┤
│                   @guidekit/server                       │
│           Token Generation · Session Management          │
└─────────────────────────────────────────────────────────┘

Documentation

Topic	Link
Getting Started	guidekit-docs.vercel.app/docs/getting-started
Provider Setup	guidekit-docs.vercel.app/docs/provider
Hooks API	guidekit-docs.vercel.app/docs/hooks
Voice	guidekit-docs.vercel.app/docs/voice
Server SDK	guidekit-docs.vercel.app/docs/server
Privacy & Security	guidekit-docs.vercel.app/docs/privacy
Error Codes	guidekit-docs.vercel.app/docs/error-codes
Architecture	guidekit-docs.vercel.app/docs/architecture
Vanilla (Non-React)	guidekit-docs.vercel.app/docs/vanilla

Development

# Prerequisites: Node 20+, pnpm 10+
pnpm install        # Install dependencies
pnpm build          # Build all 8 packages
pnpm typecheck      # TypeScript strict mode
pnpm lint           # ESLint
pnpm test:unit      # 1242 unit tests
pnpm test:e2e       # Playwright E2E tests
pnpm size:check     # Bundle size limits
pnpm check          # Full CI parity (build + typecheck + lint + test)
pnpm skills:sync    # Link agent skills for Codex/Cursor

AI agents and contributors: see AGENTS.md and llms.txt.

Project Structure

guidekit/
├── packages/
│   ├── core/       # @guidekit/core — engine
│   ├── react/      # @guidekit/react — Provider + hooks
│   ├── server/     # @guidekit/server — token auth
│   ├── vanilla/    # @guidekit/vanilla — IIFE bundle
│   ├── vad/        # @guidekit/vad — Silero VAD
│   ├── cli/        # @guidekit/cli — tooling
│   ├── intelligence/ # @guidekit/intelligence — semantic analysis
│   ├── knowledge/   # @guidekit/knowledge — BM25/TF-IDF search
│   └── plugins/     # @guidekit/plugins — plugin system
├── apps/
│   ├── docs/            # Documentation (Nextra)
│   └── example-nextjs/  # Reference Next.js app
├── scripts/             # Repo maintenance (check, stats, llms.txt)
├── skills/              # Agent skills (guidekit)
└── e2e/                 # Playwright E2E tests

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

# Fork, clone, then:
pnpm install
pnpm build
pnpm test:unit      # Make sure everything passes
# Create a branch, make changes, submit a PR

License

MIT — Copyright (c) 2025-present GuideKit