Skip to main content
Vibrisse Studio INC.
Return to Logs
LOG_06• 5 MIN READ

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

Stop paying vision-model taxes to point at a CSS flex container. Why I built Jolt (vite-plugin-jolt), a ~54 KB local-first Vite plugin that streams exact file:line:col source locations, Zustand/Pinia state, fetch mocks, and WebGL2 metrics to AI coding agents over MCP in ~280 tokens.

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:

batchfile
npm install -D vite-plugin-joltnpx jolt-mcp init --write

And in vite.config.ts:

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

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

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

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

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 `Alt+Click` pinned coordinate `src/App.tsx:71:9 · 69x22`, Zustand store `cart · 3k`, and `FAULT · 1 runtime error / POST /api/checkout -> 404` inside `<jolt-hud>`
  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

MetricManual ScreenshotsHeadless Browser MCPJolt ⚡
Runs inside your real Chrome / Safari tabYesNo (separate Chromium)Yes
Exact file:line:col + React/Vue chainNoNoYes (data-jolt-loc)
Payload per check~1,500+ vision tokensLarge DOM/A11y dumps~250–300 tokens
Live stores (Zustand/Pinia/Redux) & fetch mocksNoNoYes
WebGL2 / Three.js FPS (1% low), draw calls & 3D pickingNoNoYes
Footprint4 MB PNGsHeavy browser binary~54 KB pkg · 0 deps · 0 B prod
WebGL2 3D scene telemetry showcase (`CryoOctahedron`, `OrbitalTorus`, `SolarPrism`) showing `WebGL2 · 3 objects · 3 drawCalls` and `<jolt-hud>` reporting `120 fps · 3dc` 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.