DEV Community

Cover image for Jolt: A Local-First White-Box Bridge Between Vite and AI Agents
Quentin Merle
Quentin Merle

Posted on Originally published at vibrisse-studio.dev on

Jolt: A Local-First White-Box Bridge Between Vite and AI Agents

Every frontend developer with an AI coding assistant knows this dance:

  1. Notice a misaligned button in Chrome.
  2. Take a 4 MB Retina screenshot (~1,500+ vision tokens).
  3. Alt+Tab to your editor, paste the image, and type: "Move the second button on the checkout card a bit to the left."
  4. Watch the agent guess the wrong file, edit the wrong wrapper, or ask for the console error you forgot to copy.

When an agent is blind to your running tab, you become its human clipboard.

I built Jolt (vite-plugin-jolt) to kill that copy-paste loop. Instead of throwing pixels at a vision model, Jolt injects a tiny dev-only bridge into your real browser tab and sends ~280 tokens of exact runtime truth to your editor.

“Stop paying vision-model taxes to point at a CSS flex container.”


Act 1: The Two Dead-Ends of Frontend AI Debugging

Today, you basically have two ways to let an AI agent inspect your UI:

  1. Manual screenshots + pasting logs: Slow, expensive in tokens, and blind to React/Vue component trees, store state, or network edge cases.
  2. Headless browser MCP servers (Playwright / Puppeteer): Great for automated E2E suites, terrible for quick UI tweaks. Spawning a separate headless Chromium instance just to check padding on a localhost tab you already have open in Chrome or Safari is like using a sledgehammer to crack a nut.

Worse, headless browsers do not share your live Safari WebGL2 viewport, your authenticated session, or the exact local Zustand/Pinia state sitting in memory right now.

What I actually wanted was simple:

  • Keep working in my own browser tab (Chrome, Safari, or Firefox).
  • Alt+Click an element—or a 3D Three.js mesh—and hand my agent the exact file:line:col, computed flex/grid CSS, framework component chain, and recent causal events.
  • Ship zero bytes to production (apply: 'serve').

Act 2: How Jolt Works (and What Broke on the First Real Test)

Jolt runs inside Vite during vite dev as a zero-dependency plugin (~54 KB package tarball, ~19.4 KB gzipped dev probe in the browser, 0 bytes in vite build).

1. Local-First IPC + MCP, No Browser Extension

No Chrome extension to maintain, no cloud relay, and no sandbox terminal network popups.

Here is the whole setup in any Vite project:

npm install -D vite-plugin-joltnpx jolt-mcp init --write
Enter fullscreen mode Exit fullscreen mode

And in vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { vitePluginJolt } from 'vite-plugin-jolt';
export default defineConfig({
  plugins: [react(), vitePluginJolt()],
});
Enter fullscreen mode Exit fullscreen mode

To expose live client state or a 3D scene in one line:

import { joltZustand, joltPinia, joltThree } from 'vite-plugin-jolt/adapters';
joltZustand('cart', useCartStore);
joltPinia(pinia);
joltThree(scene, camera);
Enter fullscreen mode Exit fullscreen mode

When window. __JOLT__ is absent in production builds, every adapter becomes a silent no-op.

2. Prompt From the Browser, Preview CSS Before Touching Disk

Two small workflow details ended up changing how I work every day:

  • Prompting straight from <jolt-hud>: Hold Alt+Click on any element (or type directly inside the floating browser capsule) and hit Enter. When running an active watch loop (npx jolt-mcp listen), clicking Stop in the browser sends a [STOP_LIVE] handover signal so you immediately take chat control back in your IDE.
  • Visual Spotlight (jolt_spotlight): Instead of rewriting CSS files back and forth on disk, the agent can send temporary in-memory previewCss to the browser card. Click Apply to confirm the diff, or Cancel to revert instantly.
  • Live Chaos Mocks (jolt_mock_network): Ask your agent to return an HTTP 500 or delayMs: 1200 on POST /api/checkout in window.fetch, click the button yourself, and let the agent inspect the 10-event causal Flight Recorder (T-ms [click] -> [fetch 500] -> [error]).

Interactive  raw `<jolt-hud>` endraw  preview in  raw `Mock 500` endraw  state alongside the live floating Shadow DOM HUD running on the page ( raw `NOMINAL · Bridge Ready` endraw ,  raw `120 fps · 3dc` endraw ,  raw `joltLab · 9k` endraw ,  raw `200 LIVE` endraw ,  raw `[fetch] POST /api/checkout -> 200 OK` endraw

3. Two Honest Bugs Caught Before Publishing v0.1.0

Everything looked great in unit tests and Jolt's own Playground—until I packed the tarball and installed it inside a fresh React 19 + TypeScript + Zustand starter in /tmp:

  1. Vite plugin ordering broke JSX line numbers: Nine out of ten developers append new plugins to the end of plugins: [react(), vitePluginJolt()]. Without enforce: 'pre', @vitejs/plugin-react compiled .tsx into jsxDEV("button", ...) before Jolt ever ran, wiping out raw tags and source lines. Adding enforce: 'pre' fixed JSX, Vue SFCs, and Svelte templates regardless of array order.

Live Vite + React 19 + Zustand smoke app ("Acme Synth Checkout") showing  raw `Alt+Click` endraw  pinned coordinate  raw `src/App.tsx:71:9 · 69x22` endraw , Zustand store  raw `cart · 3k` endraw , and  raw `FAULT · 1 runtime error / POST /api/checkout -> 404` endraw  inside  raw `<jolt-hud>` endraw

  1. npx jolt-mcp init --write exited silently doing nothing: Like many Node CLIs, jolt-mcp-server.js guarded execution with path.resolve(process.argv[1]) === fileURLToPath(import.meta.url) so importing it in tests wouldn't start the CLI. Works great locally—fails completely when npm installs node_modules/.bin/jolt-mcp as a symlink to ../vite-plugin-jolt/dist/.... process.argv[1] pointed to .bin/jolt-mcp while import.meta.url pointed to the real file. Switching to fs.realpathSync() solved it immediately.

Testing your own .tgz in a disposable /tmp starter catches things unit tests never will.


Act 3: The Numbers & Where It Goes Next

Metric Manual Screenshots Headless Browser MCP Jolt ⚡
Runs inside your real Chrome / Safari tab Yes No (separate Chromium) Yes
Exact file:line:col + React/Vue chain No No Yes (data-jolt-loc)
Payload per check ~1,500+ vision tokens Large DOM/A11y dumps ~250–300 tokens
Live stores (Zustand/Pinia/Redux) & fetch mocks No No Yes
WebGL2 / Three.js FPS (1% low), draw calls & 3D picking No No Yes
Footprint 4 MB PNGs Heavy browser binary ~54 KB pkg · 0 deps · 0 B prod

WebGL2 3D scene telemetry showcase ( raw `CryoOctahedron` endraw ,  raw `OrbitalTorus` endraw ,  raw `SolarPrism` endraw ) showing  raw `WebGL2 · 3 objects · 3 drawCalls` endraw  and  raw `<jolt-hud>` endraw  reporting  raw `120 fps · 3dc` endraw  in real time

“Your agent already writes code in milliseconds. It only needed eyes in the same tab you are looking at.”

Jolt is still v0.1.0 and MIT open source. Next on the roadmap: swapping regex markup tagging for an AST pass on complex TSX/Svelte templates, adding Svelte 5 / Jotai adapters, and building interactive ui:// MCP Apps views inside IDE chat.

Try the Interactive Sandbox (Simulated Agent Loop)

If you try it on a real Vite + React/Vue/Three.js app and hit an edge case, open an issue—curious to hear what breaks first in the wild.


Proudly crafted in Beauce, Québec 🇨🇦. Interested in the alliance between immersive web engineering and local AI sovereignty? Let's connect on LinkedIn or via Vibrisse Studio!

Top comments (0)