Set up with your AI assistant
The fastest way to add Voxide to an existing project is to let the AI coding assistant you already use do it. Copy the prompt below into Claude Code, Cursor, Codex, Windsurf, Cline, OpenCode, Antigravity or GitHub Copilot — it will install @voxide/react, register capabilities that actually fit your codebase, wire up live state, and mount the widget. Or connect the Voxide MCP server so your agent always has the latest docs and examples on hand.
Let your AI assistant do it
Paste this prompt into your coding agent — it installs and wires Voxide for you.
You are integrating **Voxide** into this project.
Voxide is a capability-first voice AI SDK for the web (npm: @voxide/react). It lets this app expose its own JavaScript functions as "capabilities" that a live voice/text agent calls when the user speaks or types — no dialog trees, no intent matching. Do the full integration now.
## 1. Install (always pull the latest release)
```bash
npm install @voxide/react@latest
```
If @voxide/react is already installed in this project, re-run this exact command anyway — `@latest` forces an upgrade to the newest version even if an older one is already in package.json/lockfile.
## 2. Create the assistant (a Client Component)
Create a client component (adapt the path/framework to THIS project — e.g. `components/Assistant.tsx`):
```tsx
"use client";
import { VoxideClient, VoxideWidget } from "@voxide/react";
// publishable key — safe to ship in the browser
const ai = new VoxideClient({ publicKey: "vox_pub_XXXXXXXXXXXX" });
// Register REAL capabilities for THIS app. Inspect the codebase and expose the
// actions a user would actually ask for by voice/text (navigate, search, add to
// cart, create/update/delete, toggle settings, filter, etc.). Each capability =
// a plain-English description + typed params + an async handler that calls the
// app's real function or API.
ai.register({
exampleAction: {
description: "Clear, plain-English description of what this does.",
params: { query: { type: "string", required: true } },
handler: async ({ query }) => {
// call the app's real function / API here
return { status: "ok" };
},
},
});
// Optional but recommended: let the agent see live UI state every turn.
ai.bindState(() => ({ currentPage: typeof location !== "undefined" ? location.pathname : "/" }));
export function Assistant() {
return <VoxideWidget client={ai} accentColor="#FF6600" title="Ask us" />;
}
```
## 3. Mount it ONCE, in the true root — this step is critical, read carefully
Render `<Assistant />` in the component that wraps **every single route**, not in a page, a route-level layout, or anything nested. Getting this wrong is the #1 integration bug: if the assistant is mounted anywhere that unmounts on navigation, an in-progress voice call gets cut off every time the user changes page. `<VoxideWidget>` initialises itself — no useEffect or loading flag needed, so there is never a reason to mount it lower in the tree "to be safe."
Find THIS project's true root and mount it there — for example:
- **Next.js App Router**: `app/layout.tsx` (the top-level one, not a nested `app/(group)/layout.tsx`) — inside `<body>`, as a sibling of `{children}`.
- **Next.js Pages Router**: `pages/_app.tsx`, inside the component that renders `<Component {...pageProps} />`.
- **Vite / CRA / plain React**: the top-level `<App />` component (e.g. `src/App.tsx`), as a sibling of your `<Router>`/routes — NOT inside a specific route's element.
- **Remix / React Router**: the root layout route (`app/root.tsx` in Remix, or the top-level route with an `<Outlet />` in React Router).
- **Vue/Nuxt/Svelte or other frameworks**: whatever single component always stays mounted across every route change (root App component / root layout) — never a page-level component.
Before moving on, verify: does the file you just edited wrap literally every route, or could a user navigate to some page without passing through it? If you're not certain, look for the file that renders the router/routes themselves and mount it there.
## 4. API you can use
- `new VoxideClient({ publicKey, ui?, language? })`
- `ai.register({ name: { description, params?, handler, scope?, dangerous? } })` — `scope` can be a route like `"/checkout"` or `"/shop/*"`; `dangerous: true` prompts the user to confirm.
- `ai.bindState(() => ({ ...live state... }))` — the agent sees current UI state each turn.
- `ai.enableNavigation(router)` — auto-registers a `navigate` action (pass Next.js `useRouter()` or your router).
- `ai.setActiveRoute(path)`, `ai.onConfirmation(fn)`, `ai.use(middleware)`, `ai.setUser({ userId, email })`
- `<VoxideWidget client={ai} theme="auto" accentColor position title avatarUrl />`
## 5. Requirements
- Get the publishable key from the Voxide dashboard (replace the placeholder above).
- Whitelist your production domain(s) in the dashboard → project → Settings (localhost always works).
- Docs: https://voxide.app/docs · Package: https://www.npmjs.com/package/@voxide/react
Now: install the package, create the assistant with capabilities that genuinely fit THIS codebase, wire `bindState` to real state, and mount the widget globally. Prefer the project's existing conventions (framework, file layout, styling).Or connect the Voxide MCP server
Gives your agent live Voxide docs, examples, and integration tools right in the editor.
Run this in your project (or add --scope user for all projects):
claude mcp add voxide -- npx -y voxide-mcp
voxide-mcp#How it works
Voxide is capability-first: instead of scripting a chatbot, you expose your app's real JavaScript functions as capabilities, and the agent decides when to call them from what the user says or types. The prompt tells your assistant exactly that — so it inspects your project and exposes the actions your users would actually ask for (navigate, search, add to cart, create/update records, toggle settings, and so on), each with a description, typed params, and a handler that calls your real code.
vox_pub_…key, then paste it where the prompt shows the placeholder. Copying the prompt from your project's Integration tab pre-fills the real key for you. Remember to whitelist your production domain in project settings — localhost always works.#MCP server
The voxide-mcpserver runs locally — your editor launches it over stdio, so there's nothing to host. It gives your agent three tools it can call any time it's working with Voxide (not just the first install):
voxide_integration_guide— step-by-step instructions to add Voxide to the current project.voxide_sdk_reference— the full@voxide/reactAPI (client, register, bindState, widget props).voxide_example— copy-paste, framework-aware integration examples.
Pick your client in the panel above for the exact setup. It installs on demand via npx, so you don't need to install anything globally. To confirm it's wired up, ask your assistant something like "use the Voxide MCP to show the integration guide."
# sanity-check the server on its own (prints "ready", Ctrl-C to exit)npx -y voxide-mcpvoxide-mcp is live on npm. Until then, point the same config at a local checkout with "command": "node", "args": ["/absolute/path/voxide-mcp/src/index.js"].