Popmelt

v0.36.0

Popmelt

v0.36.0
© 2026 Popmelt
HelpPrivacyTerms
Docs

  • Getting started with Popmelt Core
  • Creating annotations with the Chat tool
  • Comparing and refining options with Explore
  • Tweaking styles with the Steer tool
  • Helping your AI understand your taste with the Imprint tool
  • Using Popmelt with Three.js and react-three-fiber
  • Add custom context to Popmelt annotations and threads
  • Recovering an annotation that won’t send
  • Inviting a teammate to a local session
  • Where Popmelt saves and sends your data

  • Annotating static objects in images
  • Annotating moving objects in video
Docs/Core

Getting started with Popmelt Core

Add Popmelt to your local app and make your first change on the page.

Open the Popmelt toolbar, click an element in your running app, ask your agent to change it, and review the result in your browser. You can reply right beside the button to refine the change.

A note on the Try Popmelt button, ready to send.

What you need

  • A web app you can already run on your computer. React is the established integration. Other supported frameworks can use experimental integrations to comment on and style page elements.
  • Node.js 18 or newer. If your app's framework requires a newer version, use that version.
  • A Codex or Claude Code account. Your agent can install its CLI during setup and guide you through signing in.

You can open your app in a regular browser or in your coding agent’s built-in browser. In either case, the command-line version of your agent (CLI) runs the conversations on the page. You can use Core locally without a Popmelt cloud account.

Install with your agent

Open your project in Codex or Claude Code and paste this prompt.

Install @popmelt.com/core in this project. Set up the matching CLI for the agent I'm using (Codex or Claude Code) in the environment that runs my dev server. If it's missing, install it using the vendor's setup instructions. If it needs sign-in, guide me through login and verify it afterward. Verify the Popmelt bridge and tell me which local URL to open.

When your agent finishes setup, open the local address it gives you. If you’re starting the app yourself, use your usual development command, such as npm run dev.

For manual setup, use the React instructions or the other framework instructions.

Make your first change

  1. Open Popmelt. Double-tap Command on macOS or Control on Windows or Linux. You should see the Popmelt toolbar. If it’s missing, check your setup.
  2. Write a note. Choose Chat (the speech bubble) from the tool menu, or press C. Click a button in your app and type what you’d like to change. For example, try “Give this button a clearer label.”
  3. Send your note. Press Enter to save the draft, then click Send beside the note to start the agent. You can also send with Command+Enter or Control+Enter.
  4. Review the change. When the agent replies, check the result on the page. To refine it, click the reply badge, type a follow-up, and press Enter.

Manual React setup

Install Core in your React project.

npm install @popmelt.com/core

Use React 18 or newer and wrap your app in PopmeltProvider. If your app has multiple routes, pass your router's navigation function so threads can reopen on the right page.

Next.js

With the Next.js App Router, put the provider in a client component.

'use client';

import type { ReactNode } from 'react';
import { useRouter } from 'next/navigation';

import { PopmeltProvider } from '@popmelt.com/core';

export function Providers({ children }: { children: ReactNode }) {
  const router = useRouter();
  return <PopmeltProvider navigate={router.push}>{children}</PopmeltProvider>;
}

Render <Providers>{children}</Providers> in your root layout. Wrap your existing Next config with withPopmelt, keeping its settings.

import { withPopmelt } from '@popmelt.com/core/next';

const nextConfig = {};
export default withPopmelt(nextConfig);

Add popmelt wrap -- before your development command, keeping any existing flags.

{
  "scripts": {
    "dev": "popmelt wrap -- next dev"
  }
}

The command starts the local bridge, and the config connects the browser to it. Next.js needs both.

Vite with React

In your React entry file, often src/main.tsx, wrap your app with PopmeltProvider. Keep any existing wrappers around the app.

import { PopmeltProvider } from '@popmelt.com/core';
import { createRoot } from 'react-dom/client';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <PopmeltProvider>
    <App />
  </PopmeltProvider>,
);

Add popmelt() to your existing Vite plugins.

import { popmelt } from '@popmelt.com/core/vite';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [react(), popmelt()],
});

Experimental framework setup

Vanilla Vite, Vue, Svelte/SvelteKit, Nuxt, and Astro support DOM annotations and style edits. Popmelt uses React internally to render its toolbar. Install the renderer dependencies alongside Core in the host project.

npm install -D @popmelt.com/core react react-dom

Vanilla Vite and Vue

Add popmelt() from @popmelt.com/core/vite to your existing Vite plugins. Mount the toolbar in the browser entry after mounting your app.

if (import.meta.env.DEV) {
  const { mountPopmelt } = await import('@popmelt.com/core/browser');
  const toolbar = await mountPopmelt({ enabled: true });
  import.meta.hot?.dispose(() => toolbar.unmount());
}

In Vue 3.5+, register app.onUnmount(() => toolbar.unmount()) for application teardown. If you use Vue Router, pass navigate: (url) => router.push(url) in the mount options so threads can reopen on the right route.

Svelte and SvelteKit

Add the same popmelt() Vite plugin alongside svelte() or sveltekit(). Mount once in your root +layout.svelte, keeping its existing content.

<script>
  import { onMount } from 'svelte';
  import { goto } from '$app/navigation';
  import { bridgeUrl, projectId } from 'virtual:popmelt/bridge';

  onMount(() => {
    if (!import.meta.env.DEV || !bridgeUrl || !projectId) return;
    let disposed = false;
    const pending = import('@popmelt.com/core/browser').then(({ mountPopmelt }) => {
      if (!disposed) return mountPopmelt({ enabled: true, bridgeUrl, projectId, navigate: goto });
    }).catch(console.error);
    return () => {
      disposed = true;
      void pending.then((toolbar) => toolbar?.unmount());
    };
  });
</script>

For plain Svelte, use App.svelte and omit the goto import and navigate option. For virtual module types, add /// <reference types="@popmelt.com/core/vite/client" /> to the app's ambient declarations.

Nuxt and Astro

In Nuxt 4.5.2 or later in the 4.x series, add the module to your existing config.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@popmelt.com/core/nuxt'],
});

In Astro, add the integration to your existing config.

// astro.config.mjs
import { popmelt } from '@popmelt.com/core/astro';
import { defineConfig } from 'astro/config';

export default defineConfig({ integrations: [popmelt()] });

Both integrations start the bridge and mount the toolbar automatically in development.

Verify your agent

After wiring up your framework, make sure the agent you want to use is installed and signed in in the same environment that starts your dev server.

AgentCheck sign-inSign in
Codexcodex login statuscodex login
Claude Codeclaude auth statusclaude auth login

If you're an agent setting up Popmelt, use the user's chosen CLI. If it is missing, install it using the provider's official instructions, then ask the user to complete any interactive sign-in. Recheck sign-in and verify the app's Popmelt bridge before reporting setup complete. Codex CLI setup · Claude Code setup

If something is missing

  • No toolbar. Check that your framework setup mounts PopmeltProvider or the standalone toolbar. In Next.js, check both the config and the development command.
  • Bridge disconnected. The bridge is the local process that connects your app to your coding agent. Check that your project's bridge is running and that the toolbar connects to it.
  • Agent unavailable. Check that the matching CLI is installed, its version is compatible, and it can run with your credentials in the terminal you used to start your app.

If a note stays on Sending, recover the annotation and check whether it reached the thread. For details about what gets stored or reported, see Where Popmelt saves and sends your data.

Next: Creating annotations with the Chat tool, Tweaking styles with the Steer tool, or Helping your AI understand your taste with the Imprint tool.

Didn't find the answer? Have an idea?

Ask a question