axsquiggle

▶️ Up and running in a minute

1. Download and connect. Download axsquiggle.mjs from Releases and run node axsquiggle.mjs: the app opens in your browser, already connected. Add it to your AI client with one line.

2. Replicate. Drop a screenshot of a screen you already have onto a frame and ask your AI to build it. It reads the image through get_review and writes the wireframe with edit_frame.

3. Change it and send it back. Edit the board, tap what bothers you, write a note, then tell your AI. It gets your notes and your edits, acts on them and replies on the note.

The AI side of these recordings is scripted: it makes the same tool calls an MCP client makes (over the bridge's POST /api/tools/<name>), and the app shows exactly what they do. Re-record with npm run dist && npm run demo (needs Playwright and ffmpeg).

Related MCP server: workflow-atlas

📦 Download

Everything is on the Releases page. Pick what you need:

Then add it to your AI client (use the real path to the file):

claude mcp add axsquiggle -- node /path/to/axsquiggle.mjs mcp

Everything stays on your machine: the bridge listens on 127.0.0.1 only and the boards are files in ~/.axsquiggle/.

🚀 Run it (pick one)

1. Just the app. Download axsquiggle.html and double-click it. One file, works offline, nothing to install. Also hostable anywhere as a static file, or try it without downloading at squiggle.axstack.dev/app.

2. The app plus AI. Download axsquiggle.mjs and run node axsquiggle.mjs (Node 18+, Windows, macOS or Linux, no npm install). It prints an address such as http://127.0.0.1:4747/: open it and the app is already connected. It opens the app in your browser for you; add --no-open to stop that.

3. From source. npm install, then npm run dev (app only), npm start (bridge + app), npm test, npm run dist (builds the two files in dist/).

🤖 Use it from an AI client (MCP)

The same axsquiggle.mjs is the MCP server: an AI client launches it and it speaks MCP on stdin/stdout by itself.

{ "mcpServers": { "axsquiggle": { "command": "node", "args": ["C:/tools/axsquiggle.mjs"] } } }

Claude Code: claude mcp add axsquiggle -- node /path/to/axsquiggle.mjs. If a bridge is already running (step 2) the client joins it, so the app you have open and the AI share one board. Clients that connect to a URL instead can use http://127.0.0.1:4747/mcp with Authorization: Bearer <token> (the token is in ~/.axsquiggle/token).

See it in action

An AI client drafts the board, you review it in the app, and it acts on your notes:

The prompt is an example. The draft, the note and the update are real bridge calls (draft_board, get_review, edit_frame, resolve_notes), shown as the app displayed them.

👀 Preview

The Preview button in the top bar (or Shift+V, or Export → Preview) opens a realistic preview of every screen: buttons, inputs, cards and lists rebuilt as real controls inside a phone or browser, with your links working. Pick the look with the style menu or press S to cycle (Clean, Material, Dark, Bold brand, Minimal). The same page is served by the bridge at /api/export/preview?style=dark, and Export → Preview saves it as one offline file.

Pick a look: Clean, Material, Dark, Bold brand or Minimal, on desktop or phone frames.

🏢 Locked-down and corporate machines

🗂️ Layout

• src/core/ pure modules, no DOM: recognize (stroke recognition), semantics (roles + smart sizing), layout (outline builder and row edits), exporters (SVG, Figma SVG, Excalidraw, Markdown, HTML), model (validation, example board, raw JSON), trace (photo of a sketch to shapes). agent (read/edit/diff/review functions an outside AI uses), connect (arrow attach + routing), links, parts, search.

• src/ui/ canvas, panels, dialogs. server/ the AI bridge (HTTP + MCP). worker/ the same bridge as a Cloudflare Worker for the hosted app (one-click Activate MCP, no install; see worker/README.md). tests/ Vitest suites.

💾 Saving and opening

The board autosaves in the browser. New starts an empty drawing (Undo brings the old one back). To keep it as a file (or move it, or version it in git), press Ctrl/Cmd+S or Save: one small JSON file, {"axsquiggle":1,"frames":[...]}. Ctrl/Cmd+O, Open, or dropping the file on the canvas brings it back (Undo reverts). In Chrome and Edge Save writes back to the same file; elsewhere it downloads. It is exactly what an AI gets from get_board (format json), and an AI can hand a whole board back with load_board.

⌨️ Keyboard

• Space (or Ctrl/Cmd+K) lists every shortcut in one panel. Press a key and it runs, or press Tab / / to search.

• F is the Flow tool: draw, type, select and move with no tool switching.

• / on the canvas stamps elements and your saved parts: /radio, /cb, /btn, /field, /card.

• Esc undo, Shift+Esc redo, Ctrl+F search all frames, 1-9 jump to a frame, ? the animated help.

• B saves the selection as a reusable part, L links it to another frame, I plays the board click-through.

Space (or Ctrl/Cmd+K) lists every shortcut, / stamp and saved part in one compact panel: press a key and it runs, or press Tab or / to search (Enter runs the highlighted row). F Flow tool (draw, type, select and move with no tool switching), ? (the button at the end of the top row) opens the animated help, Ctrl+F search all frames, / the stamps and parts list, Esc undo (the first one after a drawn shape gives you the sketch back; with something selected it deselects first), Shift+Esc redo, Ctrl+Z/Ctrl+Shift+Z too, Backspace/Del delete, Ctrl+A/Shift+click/drag a box to multi-select, B save the selection as a reusable part (stamp it with /name after tapping the canvas; name it nav-bar: top navigation links to add a one-line description), L link the selection to another frame, I click-through play mode. Radios and checkboxes are typed in a run: tap the canvas, type /radio, then a label and Enter makes the next one below (empty Enter ends); in the Outline, Enter on a radio/checkbox row does the same. Two or more form a group with a border (Q puts a border around any selection) that always hugs its contents. A label can run to several lines (Shift+Enter); a later line that starts with spaces is a smaller, muted sub-label, and in the outline text indented under a radio, checkbox or list item becomes its sub-label. Boxes grow to hold their text, rows re-align and borders re-fit on their own: nothing needs resizing by hand. An input takes ghost placeholder text: input Email "you@example.com" (or an indented line under it), and the Outline has a field for it. An image or card takes a height: image Cockpit view {h=320} (default 160). An AI can also resize one later with edit_element set_height; whatever sits below it moves with its edge. Basic controls: /dropdown Country "Pick one", /search, /tabs Day, Week, Month (a button group), /badge New.

Tap the canvas and type /radio Contact by: Email, SMS (text before the colon titles the group, above its border), /cb Remember me, /btn Save, Cancel, /field, /img, /card to stamp elements.

🔁 AI bridge (draft, review, action)

Let an outside AI draft the first screens, edit them yourself, leave review notes, and send it back to be actioned.

Start the bridge (see "Run it" above), add it to your AI client (see "Use it from an AI client"), and open the app through the bridge address (or press MCP in the header and paste the URL and token). Then:

1. The AI calls draft_board with outline text (the same syntax as the Outline panel, button Sign in -> 2 links frames).

2. You edit the draft in the app and write review notes (Review tool, loop the elements a note is about). Your edits sync to the bridge.

3. You tell the AI, in its own chat, that you have left notes. It calls get_review and gets the open notes (with the elements each points at), what you changed since its draft, and the board. Nothing is pushed to it: all AI works through MCP.

4. It acts with edit_frame / edit_element, then resolve_notes with a short reply per note. Its edits arrive in the app as one undoable change; resolved notes show struck through with its reply.

An Image element (a box with a cross) has a description, the words underneath it (select it and press Enter, or just type under it), which the AI reads. It can also show a real picture: select it and press P, or drop / paste an image onto it (scaled to 800px inside the board file); Shift+P takes it out again.

A photo of a hand sketch or a screenshot dropped onto a frame (the Image button, paste, or drag) comes back to the AI as an attached image in get_review (or get_board with include_images), so it can look at it and build the wireframe itself. K traces the image into shapes offline (no AI): boxes, circles, arrows and scribbled paragraphs are recognised, handwriting becomes "Label" placeholders.

Tools: get_board, draft_board, edit_frame, edit_element, delete_frame, add_note, get_review, resolve_notes, get_frame_svg, plus board management: list_boards, new_board, switch_board, rename_board, delete_board.

Several boards. The bridge keeps named boards in ~/.axsquiggle/boards/<name>.json (an earlier single board.json becomes default; deleted boards move to .trash/). One is open in the browser; every tool acts on it unless given board_name. An AI should list_boards first and new_board for unrelated work instead of adding to the open one. In the app, Shift+B (or the board name in the toolbar) switches or starts a board; opening a board starts with an empty Undo history. REST equivalents: GET /api/boards, POST /api/tools/<name>, GET/PUT /api/board, GET /api/review, GET /api/events (SSE).

🏷️ Releases

A release is a git tag. Pushing a tag that starts with v runs .github/workflows/release.yml, which runs the tests, builds the downloads and publishes them (with checksums and generated notes) on the Releases page.

npm version 0.2.0 --no-git-tag-version   # optional: keep package.json in step
git commit -am "Release 0.2.0" && git tag v0.2.0
git push origin main v0.2.0

Check dist/ locally first with npm run dist. Nothing is built from a branch: only tags publish.

📄 License

MIT