Visit zigzag.diy
ZigZag is a visual embroidery editor built in Rust for performance, with
built-in MCP (Model Context Protocol) support so AI agents can create and
edit designs alongside you. Turn SVG artwork into stitches, fine-tune it in
the editor, and export PES, DST, EXP, JEF, or VP3 for broad compatibility
with embroidery machines—or send designs directly to a Brother Skitch
(PP1) over Bluetooth.
Draw in Illustrator, draw in ZigZag, or let an agent draw. The Rust engine
and zigzag command-line tool power the same workflow outside the editor.
See ZigZag in action
zigzag-demo.mp4
Stitching on a Brother Skitch (PP1)
Download the video (MP4, 1080p)
· Original post on X.
Download for Mac
Download ZigZag.dmg
For Apple Silicon and Intel Macs, macOS 11 or later. Open the DMG, then drag
ZigZag into Applications. The release is signed and notarized by Apple.
No Rust installation is needed.
Or with Homebrew:
brew install --cask simpsoka/zigzag/zigzag
To update a Homebrew installation:
brew upgrade --cask --greedy simpsoka/zigzag/zigzag
Starting with version 0.1.3, ZigZag also offers an in-app updater: it tells
you when there's a newer release and installs it when you say (ZigZag ›
Check for Updates…).
Download for Windows
Download ZigZag for Windows
— the ZigZag-<version>-x86_64-windows.zip asset on the latest release.
For 64-bit Windows 10 (version 1709 or later) and Windows 11. Unzip it and
double-click ZigZag.exe. Windows SmartScreen warns on apps without a
Microsoft-trusted signature the first time they run; click More info →
Run anyway. No Rust installation is needed.
Download for Linux
Download ZigZag for Linux
— the ZigZag-<version>-x86_64-linux.tar.gz asset on the latest release.
For x86-64 Linux desktops with glibc 2.35 or newer (Ubuntu 22.04+, Debian 12+),
X11 or Wayland, and OpenGL. Extract the archive and run ./zigzag-studio
inside the extracted folder. It also includes the zigzag CLI and
zigzag-mcp bridge; no Rust installation is needed. See the included
README.txt for runtime dependencies and Bluetooth setup.
Release notes and checksums
· Changelog
· Publishing a release
zigzag/
src/svg.rs SVG import (usvg): fill and stroke parts, transforms, text
src/document/ editable document; settings saved back into SVG ids,
layout edits as SVG transforms, lettering
src/params.rs stitch settings tokens + fabric presets
src/stitch/fill.rs tatami fill (scanline sections, staggered rows)
src/stitch/satin.rs satin columns: two rails, auto-satin, underlays, short stitches, lean
src/stitch/columns.rs shapes that branch or have holes, cut into satin columns
src/stitch/stroke.rs running / triple-run stitch
src/boolean.rs polygon booleans and offsets (i_overlay)
src/design.rs planner: overlap removal, cap order, routing, trims
src/route.rs travel out of sight: a way through fills and under what covers
src/checks.rs digitizing checks (sizes, widths, lettering, hoop)
src/machine/profile.rs machine profiles: hoops and file format, built in (profiles.json) or your own
src/formats/ PES (+PEC), DST, EXP, JEF, VP3, Skitch PEN writers;
PES/PEC/DST/EXP/JEF readers; preview; worksheet
src/machine/ Skitch Bluetooth protocol (+ btleplug client, `ble` feature)
src/studio/ editor (egui on OpenGL via glow) + MCP server (`gui` feature)
src/mcp_bridge.rs stdio ↔ HTTP bridge for MCP clients that launch a command
Build
cargo build --release # CLI + MCP bridge, no system deps
cargo build --release --features gui,ble # + the studio editor and Skitch upload
Linux needs the usual X11/Wayland and OpenGL dev libraries for gui. libdbus
is vendored for ble.
Stitch types
| Type |
What it does |
Works on |
| Fill (tatami) |
Staggered rows, any angle, with underlay (edge walk + rows) and pull compensation |
Filled shapes |
| Satin |
Zigzag column between two rails, with center/contour/zigzag underlay, pull compensation and short stitches on tight curves; plain, S-stitch or zig-zag top stitching; stitches square across or leaning (lean=8); several threads across the column (multicolor satin) |
Strokes (any width); Ink/Stitch-style two-rail paths with rungs; filled shapes: rings use inner/outer outline, bars and crescents split at their tips, letters and other shapes that branch or have a counter are cut into columns where the branches part (a P into its stem and bowl, a T into bar and stem), or border follows the outline |
| Run |
Running stitch, single or triple (bean) |
Strokes and outlines |
| Contour |
Rows that follow the outline inward, or one spiral out from the center (Ink/Stitch's circular fill) |
Filled shapes |
| Blanket |
E-stitch: a line with prongs into the shape |
Edges, appliqué |
| Appliqué |
Placement line → stop → tack-down → stop → satin cover |
Filled shapes |
| Manual |
Every path point is a needle point |
Imported machine files, pen tool |
| Meander |
One wandering line through the shape, quilting style: light and soft |
Filled shapes |
| Ripple |
Open running-stitch rows following the outline, or one spiral |
Filled shapes |
| Cross-stitch |
A grid of X's, sewn as rows of half-crosses out and back |
Filled shapes |
| Tartan |
Woven stripes in several threads (a mirrored sett you edit in the panel), each thread its own color block |
Filled shapes |
Satins wider than 7 mm are auto-split (shorter, staggered stitches) and
use auto spacing (narrow columns more open, wide ones denser).
Planner features:
- Remove overlaps: fill hidden under later objects isn't sewn (keeps 0.5 mm of overlap).
- Cap order: center-out, bottom-up, grouped by color, still respecting layering.
- Routing: travel stitches stay out of sight: straight across where a straight line stays inside the fill, otherwise round the inside of its outline (Ink/Stitch's underpath), otherwise any way through the fill (round its holes, through its necks), under a satin that's about to be sewn, or under whatever is sewn later on top. An object's last piece is sewn toward the end the next object can be reached from. So satin lettering sewn stroke by stroke needs cuts only between letters when each stroke is followed by one that covers the way to it (a T's stem before its bar; an E's bars before its stem). A fill in separate parts is sewn part by part, each part's underlay and top together. So a fill with cut-outs, or a dither in scattered blocks under another color, is sewn with few or no cuts. Trims only where none of that works (up to 50 mm of travel).
- Sewing control per object: a start and an end point (where the thread comes in and leaves, so the next object is close), trim after, stop after (to lay foam or trim appliqué). What's left to cut is the document's Connect bar: drag it to sew across gaps up to N mm (between objects, or the parts of one) with running stitches instead of cuts. Those stitches show, so the panel counts the cuts saved as you drag and the canvas lights up what would be sewn.
- Fabric presets: standard, thin cotton cap, structured cap, knit.
- Checks: narrow fills, wide/narrow satins, small lettering, tiny gaps, fully covered objects, hoop fit.
- Group colors: reorder to cut thread changes without breaking layering.
Mac app
On a Mac with Rust and the Xcode command line tools
(xcode-select --install):
packaging/macos/make-app.sh --install # builds ZigZag.app and copies it to /Applications
packaging/macos/make-app.sh --dmg # also makes dist/ZigZag-<version>.dmg to share
packaging/macos/make-app.sh --universal # one app for Apple Silicon and Intel Macs
packaging/macos/make-app.sh --release # the DMG to publish: universal, signed, notarized
--release signs with your Developer ID and has Apple notarize the app and
the DMG, so it opens on any Mac without warnings. Once, beforehand: add a
Developer ID Application certificate (Xcode › Settings › Accounts › Manage
Certificates › +), make an app-specific password at account.apple.com, and
save the notarization credentials in your keychain:
xcrun notarytool store-credentials zigzag-notary --apple-id YOUR_APPLE_ID --team-id YOUR_TEAM_ID
The app bundles the studio, the zigzag command-line tool and the MCP
bridge. To use the command line from anywhere:
ln -s /Applications/ZigZag.app/Contents/MacOS/zigzag /usr/local/bin/zigzag.
For Claude Desktop, point the MCP config at
/Applications/ZigZag.app/Contents/MacOS/zigzag-mcp.
Without --release the app is signed ad hoc, not notarized. It opens normally on the Mac that
built it. On another Mac, macOS blocks it the first time: open System
Settings › Privacy & Security and click Open Anyway (on macOS 14 and earlier,
right-click the app and choose Open instead). macOS asks for Bluetooth
permission the first time you send to the Skitch.
Studio
The approved embroidered icons live in packaging/macos/AppIcon.png (light)
and packaging/macos/AppIcon-dark.png (dark). The Mac build regenerates both
multi-resolution .icns files; run bash packaging/macos/make-icons.sh to
regenerate them separately. Finder and the unopened app use the light icon.
While the studio is running, its Dock icon follows the app's light/dark theme,
including the ZIGZAG_THEME=light|dark override.
zigzag-studio [design.svg|logo.png] [--mcp-port 7878 | --no-mcp | --mcp-stdio]
Laid out like Illustrator, styled like a Mac app:
Agents (MCP)
The studio runs an MCP server on http://127.0.0.1:7878/mcp (Streamable HTTP,
localhost only, Origin-checked). Agents edit the live document you're looking at
(the tab in front), and every call is one undo step.
MCP in the status bar (bottom right, next to the Skitch) shows whether agents
can reach the studio: a gray dot while it waits, green once a client has connected,
blue and pulsing while calls come in, red if the server couldn't start. Click it for
the address, the commands to connect Claude Code and Claude Desktop (with Copy
buttons), the clients that have connected, the recent tool calls (failed ones in red,
with the error on hover) and the tools on offer.
Claude Code:
claude mcp add --transport http zigzag http://127.0.0.1:7878/mcp
Claude Desktop / stdio clients (claude_desktop_config.json):
{ "mcpServers": { "zigzag": { "command": "/path/to/zigzag-mcp" } } }
zigzag-mcp forwards to the running studio. Use --port N if you changed it.
With "args": ["--headless"] it works without the app open: the same tools on a
document no one is watching (zigzag-studio --mcp-stdio), kept only when the
agent saves or exports it.
Tools:
get_design, add_svg (place/scale artwork in mm), set_object, delete_object, move_object
transform_objects (size, scale, rotate, mirror, move), duplicate_objects
add_text, edit_text, list_fonts
set_document (machine, shortest stitch, lock stitches, how narrow a satin may be before it's warned about, fabric, hoop as a standard or any WIDTHxHEIGHT in mm, overlaps, cap order, preview color), list_machines, group_colors
render_preview (returns a PNG of the stitches), check_design, get_svg, select
export with objects: true also writes FILE.objects.json: which object each stitch, jump and trim in the machine file is for, so a checker can name the shape behind a fault
open_file (SVG, machine file or image, in a tab of its own), list_documents, switch_document, new_document, undo, save, export (machine formats or html worksheet; without a format, the one the path ends in, or else the one the document's machine reads), send_to_skitch, machine_status
- Any tool that changes the design takes
terse: true for a short answer (ok, the names of objects added, and the design problems that are new) instead of the whole object; on batch it covers every step.
trace_image (PNG, JPEG, WebP, GIF, BMP or TIFF logo → shapes, colors snapped to a thread chart), add_outline (a satin or running-stitch outline on a filled shape, as an object of its own), round_corners, simplify (VectorCraft's 0–100 levels, or Auto), clean_up, simplify_design (fewer threads, small details and trims for the whole design; dry_run to see what it comes to)
batch: several calls in one, all or nothing and one undo step; later steps can use earlier results ("$0.added.0.name")
Arguments a tool doesn't take are refused with the ones it does (a misspelt
widht_mm isn't silently ignored), and each tool says whether it only reads.
Try asking: "Draw a 50 mm round badge with mountains and a sun for my thin
cotton cap, check it, and show me the preview."
CLI
zigzag convert logo.svg -o logo.pes -o logo.jef -o preview.png -o sheet.html [--fabric thin-cap] [--hat]
zigzag convert old.dst -o old.pes # machine files convert too
zigzag convert logo.png -o logo.pes # PNG, JPEG, WebP… logos are traced first
zigzag info logo.svg # stats + checks
zigzag fabrics # list presets
zigzag convert logo.svg -o logo.exp --machine melco-summit # that machine's hoop and shortest stitch
zigzag convert logo.svg -o logo.dst --min-stitch 0.4 --lock triangle:0.5:3
zigzag machines # list machines
zigzag convert logo.svg -o logo.exp --objects # and logo.exp.objects.json: which object each stitch is for
zigzag skitch info | status # needs --features ble
zigzag skitch send logo.svg --trace
Illustrator workflow
Export with File → Export → Export As → SVG (Styling: Presentation Attributes,
Object IDs: Layer Names). Outline text, or it falls back to system fonts.
Opening the ZigZag-saved SVG back in Illustrator keeps the settings in the
layer names.
Name layers or objects to set their stitching. Illustrator's _x3D_-style
escapes are decoded, and group settings apply to everything inside the group.
| Token |
Meaning |
fill satin run skip |
stitch type |
a=45 |
fill angle (degrees) |
s=0.3 |
row / zigzag spacing (mm) |
l=3 |
max stitch length (mm) |
pc=0.2 |
pull compensation (mm per side) |
w=3 |
satin width (mm) |
border |
satin along a filled shape's outline instead of across it |
u=0 |
underlay off |
ul=center+contour+zigzag |
satin underlay passes (ul=none) |
ss=0 |
short stitches off |
r=3 |
running passes (3 = bean) |
contour blanket applique manual |
the other stitch types |
split=7 |
satin auto-split length (mm); split=0 off |
t=e8a33c |
thread color override |
o=2 |
sewing order |
stroke.… |
applies only to the stroke of an object that also has a fill, e.g. stroke.run (the object's other settings are its fill's) |
Example layer names: logo fill a=45 s=0.35, title satin, outline stroke.satin stroke.w=1.5.
Skitch over Bluetooth
The Skitch window (the toolbar's Send button or File › Send to Skitch…)
runs the whole job, like a slicer's device page follows a print: the design
on the left, what to do on the right, and the steps across the top
(Connect · Home · Send · Trial · Sew · Done).
- Connect and pair. It scans for the Skitch. The first time, hold the
Skitch's Bluetooth button until it beeps, then Connect (or Try Again);
if the computer asks to pair, accept. On a Mac the Skitch never appears
in System Settings › Bluetooth (it's a Bluetooth LE device): it pairs
when ZigZag connects. Allow ZigZag to use Bluetooth if macOS asks
(Privacy & Security › Bluetooth). Close Artspira first: the Skitch talks
to one app at a time.
- Home. A machine just turned on asks to be homed (frame off, Accept,
frame back on); the window shows the steps and moves on when it's done.
- Send: the hoop with the design where it will sew: As Placed (where
it sits in the studio's hoop, so you can put it high on a cap) or
Centered; the threads to have ready, in sewing order, by Brother
Embroidery name and number; a "before you sew" checklist; Send Design.
- Trial run (Brother's name for it; on by default after sending): press
Accept on the machine and the needle goes around the design's outline
without sewing, so you can check it clears the frame's magnets, seams and
the brim. Trial Again whenever you rehoop.
- Sew: Start, then press Start on the machine. The picture shows what's
sewn, faded where it hasn't been yet, with the needle and the thread on
now; under it, a timeline of the threads with the needle's place. The
side shows progress, time left, the thread on now and the next one, and
at each thread change exactly which thread to put on. The canvas and the
status bar follow along too.
- Start / Pause / Stop. Start (or Resume, or Sew Again) readies the
machine; Pause is the Skitch's own Start/Stop button (it can't be paused
over Bluetooth); Stop ends the job, taking the design off the machine.
While paused, drag along the timeline or step the needle by 1, 10 or 100
stitches or back to the thread's start, then Resume.
- Errors say what they are and what to do (thread breaks, bobbin, needle
plate, frame). After a thread break the needle goes back over the gap
(6 stitches for the top thread, 2 for the bobbin, as Artspira does).
- Minimize it (–) to keep working while it stitches: the canvas is your
design again, and the machine's icon at the right of the status bar shows
what it's doing and how far, with a small bar (click it to bring the
window back). The window comes back by itself when the machine needs you:
a thread change, an error, or the end.
- The ••• menu also links to Brother's Skitch how-to videos (threading,
the bobbin, the frame, a thread break, tension, cleaning).
- The window's ••• menu can connect to a simulated machine, which does
each step on the machine by itself, to try it all without a Skitch.
Agents can send_to_skitch and follow along with machine_status. The
protocol was reverse-engineered (see NOTICE), so avoid firmware updates.
Working out undocumented commands
Thread tension isn't a Bluetooth setting on the Skitch: it's the tension
dial on the machine. Speed is fixed (about 400 stitches a minute). The
machine does report a block of settings, and Artspira has a settings
screen, so two tools are here for working out what else it can do:
- Settings bytes (in the Skitch window, under the machine's details):
reads the settings block the machine reports. Read it, disconnect, change
one setting in Artspira, close Artspira, reconnect and read again: the
bytes that changed are marked. Every read is kept in
skitch-settings.log beside the panel layout. On the command line:
zigzag skitch settings --label "what changed" --log settings.log.
zigzag capture FILE lists the Skitch conversation in a
Bluetooth recording of Artspira, by command name, with changed settings
bytes in [brackets] (--all for the upload and polling too, --raw for
every ATT operation). It reads both:
- iPhone: install Apple's Bluetooth logging profile on the phone
(developer.apple.com › Bug Reporting › Profiles and Logs), restart it,
plug it into the Mac, and in PacketLogger (Apple's Additional Tools
for Xcode) choose File › New iOS Trace; save the trace (
.pklg).
- Android: Developer options › Enable Bluetooth HCI snoop log, then
adb bugreport and take btsnoop_hci.log from it.
Writing settings stays out of ZigZag until a layout is known and a
write of the machine's own settings, unchanged, reads back the same.
Ink/Stitch parity
Checked against Ink/Stitch's features and tool docs:
| Ink/Stitch |
ZigZag |
| Running, bean, manual stitch; satin column (two rails with rungs), E-stitch; tatami, contour, circular (spiral) fill |
✓ |
| Ripple, meander, cross-stitch and tartan fills; S-stitch, zigzag and multicolor satin |
✓ |
| Params per object with fabric-aware defaults; start/end commands; trim and stop commands |
✓ (Stitch panel's Sewing row) |
| Auto-route (travel inside fills, underpath along the outline, under what's sewn on top), Jump to Stroke |
✓ (document's Connect bar) |
| Simulator, stitch plan preview, density map, stacking-order labels |
✓ |
| Lettering (system fonts, arcs, text on a path, multi-line, case, scale), thread palettes, Match All, thread kits |
✓ (Brother and Janome charts) |
| Duplicate params, select by type, flip satin direction, test swatches, cleanup, troubleshoot (Issues) |
✓ |
| Import stitch files and edit at stitch level; PES/DST/EXP/JEF/VP3/PEC |
✓ |
| Gradient fill, guided fill; redwork, cutwork; pre-digitized fonts; 60+ thread brands; PDF print |
not yet |
Hatch parity
Checked against Wilcom Hatch's core feature set:
| Hatch |
ZigZag |
| Tatami, satin, run/triple run, contour fill, blanket, appliqué, manual stitches |
✓ |
| Auto underlay, pull compensation, auto spacing, satin auto-split, short stitches |
✓ |
| Fabric settings that set densities and compensation |
✓ (4 presets) |
| Lettering with TrueType fonts, straight, arc and path baselines, typed on the canvas |
✓ (system fonts) |
| Select, move, resize, rotate, mirror, duplicate, copy/paste, align to hoop |
✓ |
| Digitize shapes and manual stitches by hand |
✓ (pen tool) |
| Remove overlaps, color sequencing, re-order objects |
✓ |
| Stitch player, show needle points, grid, measure |
✓ |
| Open and save PES, DST, EXP, JEF, VP3 |
✓ (VP3 write only) |
| Production worksheet |
✓ (HTML) |
| Auto-digitize bitmaps |
✓ (Image Trace: flat logos, posterized photos, centre lines) |
| Built-in embroidery fonts, monogramming, multi-hooping, motif/pattern fills, 3D foam |
not yet |
Status
Verified:
- 136 library tests, 153 editor/MCP tests (UI interactions via egui_kittest, a full
agent workflow, a real HTTP JSON-RPC session, atomic batches, the Skitch flow
against a simulated machine), with and without Bluetooth built in, plus the
222 tests of the vendored Image Trace.
- Every writer (PES, DST, EXP, JEF, VP3) reads back through pyembroidery with
identical stitch positions; our readers read pyembroidery-written files.
- PEN output checked against hand-computed sequences.
- Studio run on Mesa OpenGL and driven by an agent over MCP.
Tested on a real Brother Skitch (PP1).
Screenshots and videos
Start the studio with ZIGZAG_CAPTURE=<folder> and ⌃⌥⌘S saves the window as
a full-resolution PNG; ⌃⌥⌘R starts and stops recording it.
packaging/media/encode.sh <folder>/take-001 demo turns a recording into
demo.mp4 and demo.gif (needs ffmpeg).
Credits
See NOTICE, and THIRD-PARTY-NOTICES.md for
the licenses of the libraries ZigZag is built from (regenerate it with
packaging/licenses/generate.sh after changing dependencies). PES/PEC/DST layouts
and the Brother palette are from pyembroidery (MIT).
Image Trace is vendored from VectorCraft
(MIT OR Apache-2.0), whose curve fitting, live corners, snap targets and colour
difference were also ported (see vendor/README.md).
Tatami, satin and short-stitch approaches follow Ink/Stitch.