Skip to content
GUIJam
Please leave a star!11 stars

Architecture

GUIJam is four pieces, each with one job. Only one of them ever writes to your project.

  1. GUIJam widget

    Browser, in a shadow root

    Toolbar, drawing, panels. Talks only to your dev server.

    HMR channel
  2. guijam() plugin

    Your dev server

    Source locations, in-memory previews, hot-update results.

    WebSocket + token
  3. gjd daemon

    Rust, localhost only

    Reads source, routes requests, validates and journals every write.

    stdio
  4. Your 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.

Documentation