Architecture
GUIJam is four pieces, each with one job. Only one of them ever writes to your project.
GUIJam widget
Browser, in a shadow root
Toolbar, drawing, panels. Talks only to your dev server.
HMR channelguijam() plugin
Your dev server
Source locations, in-memory previews, hot-update results.
WebSocket + tokengjd daemon
Rust, localhost only
Reads source, routes requests, validates and journals every write.
stdioYour AI CLI
Headless, no write tools
Claude Code, Codex, OpenCode and more. Answers with structured edits.
The widget#
The toolbar and panels run in your page, inside a shadow root, so your app's styles never leak into them and theirs never leak out. The widget is built with React and FigUI, a set of Figma-style components.
It talks only to your dev server: over Vite's hot-reload channel, or through a localhost relay in Next.js. It has no endpoint of its own and no token in page JavaScript.
The dev server plugin#
guijam() in Vite, the Nuxt module, the Astro integration and withGuijam() in Next.js all do the same three things:
- Add source locations to elements, so each one knows the file, line and column that rendered it. See Source locations.
- Serve previews from memory in place of the files on disk. See Live previews.
- Report whether each hot update succeeded, so a broken preview never reaches the page silently.
In Next.js, withGuijam() adds a loader that marks elements and serves previews, loads the toolbar through instrumentationClientInject, and starts a relay on localhost that connects the page to gjd with a per-session token.
The gjd daemon#
gjd is a small Rust program, installed with the guijam package for your platform. It's the only process that writes to your project. It:
- Reads the source of the element you picked.
- Routes each request: an exact edit it can make itself, or a request for your CLI. See Request lifecycle.
- Runs your CLI and validates every edit it proposes against the current file.
- Journals each commit, so undo restores files exactly.
It listens on localhost only, requires a per-session token, and stops after 30 minutes with no dev server connected. There is one daemon per project.
When the dev server starts and finds a daemon from another GUIJam version still running, it stops that one and starts the version you installed, so an upgrade takes effect on your next dev server start. When the daemon stops, any AI tool run still in progress stops with it, so nothing keeps using your plan in the background.
Your AI CLI#
Your CLI receives the relevant code inline and answers with structured edits. It's never given tools that can change files. See AI tools.
One message format#
The widget, the plugin and the daemon share one set of message definitions, written as JSON Schemas. TypeScript and Rust types are generated from them, so the three processes can't drift apart.