Skip to main content
Glama

To install: paste this repository's URL into your agent and ask it to install paintress. Agents that need a precise procedure will find one at the end of this file.

What it is

paintress is a UI design tool for AI agents. You describe a screen in chat, the agent draws it into a design file, and you watch it appear in your browser — no canvas to drag, no design app to learn.

You point instead of describing: click any element in the viewer and it gets a short number (#1), so "make #1 blue" changes exactly that element.

Designs are plain JSON files inside your project, so they diff and commit like code.

The agent does the reading and writing, through MCP tools or the CLI. The browser viewer is for looking, clicking and marking.

Part

Purpose

MCP tools

paintress_viewer, paintress_new, paintress_doc_info, paintress_query, paintress_get, paintress_update, paintress_insert, paintress_delete, paintress_move, paintress_batch, paintress_validate, paintress_convert, paintress_preset, paintress_project, paintress_font, paintress_audit, paintress_establish, paintress_adjust, paintress_component, paintress_render, paintress_screenshot, paintress_marks

CLI

the same operations plus the viewer process, for use without an agent

Viewer

local web server: renders a document, highlights changes, hands back clicked nodes as #1, #2, …

Screenshot

PNG of a canvas or one board; scale 0.2–2 (default 0.8), either edge capped to 8192px

Related MCP server: gitcad

Files and formats

New files are .ptr — paintress's own flavor of the same JSON design document. Existing .pen files open, edit and render unchanged; only the extension differs.

Two project-level files keep a project consistent. They live at the registered project root — the directory you watch, not the folder of an individual design file — and they belong in version control next to the designs. paintress_project (and the viewer's designSystem block) returns their exact paths and reports any nested duplicate that would split the design system:

File

Holds

__preset.ptr

design tokens (colors, radii, spacing, font sizes, font families), preset groups and the font registry

__components.ptr

reusable components (nodes marked reusable)

Requirements

Node.js 22 or newer.

Install

npm install -g paintress

Then register it with the agent(s) you use:

paintress doctor            # what is installed and which clients already have the entry
paintress install           # write the MCP entry into every detected client config
paintress install pi cursor # or only the ones you name

install merges a single entry, preserves everything else in the file, and writes a *.bak-<timestamp> backup before touching it. Running it twice changes nothing.

CLI

paintress mcp                                              start the stdio MCP server
paintress new <file> [--name n] [--width n] [--height n] [--fill c]
                      [--layout vertical|horizontal|none] [--padding n] [--gap n] [--force]
                                                           create a design file (one empty board)
paintress info <file>                                      document summary
paintress convert <file.pen> [out.ptr] [--force]          convert .pen to .ptr (source untouched)
paintress query <file> [--type t] [--name n|--regex]    find nodes
paintress get <file> <id> [--depth n]                   read a node subtree
paintress update <file> <id> '<patch-json>'             shallow-merge attributes
paintress insert <file> <parent> '<node-json>'          insert a child node
paintress delete <file> <id>                            remove a node
paintress move <file> <id> <parent> [--index n]         reparent a node
paintress batch <file> '<ops-json>'                     several operations at once
paintress validate <file>                               check against the format spec
paintress preset list|set|remove|seed|set-group|remove-group ...
                                                           tokens, groups and the starter scale
paintress font list|add|remove|default ...                project font registry
paintress audit <file>                               read-only design-system audit
paintress establish <file> [--apply]                propose tokens / preset groups (dry-run by default)
paintress adjust <file> --key k --value v [--apply] preview or apply a design-system adjustment
paintress component list|insert|add ...                  project component library
paintress render <file> <out.html>                      write the canvas as HTML
paintress shot <file> <out.png> [--scale 0.2..2] [--board id|name]  render to PNG (default 0.8)

paintress web [--port n] [--bind auto|loopback|all] [--idle ms] [--foreground]
                                                        ensure the viewer is running (idempotent, returns at once)
paintress ping | status | stop                          viewer control
paintress watch <name> <dir> [--depth n] | unwatch <name>  register a directory to browse
paintress attach <name>                                 keep the viewer alive while an agent works

paintress install [client...] [--dry-run]               write MCP config entries
paintress doctor                                        show client configuration state
paintress mcp-config <client>                           print the config snippet for one client

Viewer

paintress web
paintress watch demo ./demo
# open http://localhost:6033/demo

paintress web is idempotent and returns immediately: if a viewer is already running it prints that process's pid / port / http, otherwise it starts one and opens the viewer window on it. Either way the command is safe to run before every drawing session — there is never a second instance, and the window is opened by the program, in the desktop browser (--foreground keeps the process attached to your shell when you want its log; paintress stop is how you replace a running viewer, e.g. on another port). Under WSL the window lands in the Windows browser, never in a browser inside the distro.

The port is not a constant you should memorize: it is chosen at startup and reported back. The default is 6033; if that port is unusable the viewer walks 6033 → 6133 → 6233 on 127.0.0.1, and if none of them can be reached from the host it re-binds the same three ports on 0.0.0.0 (six candidates, first usable one wins, otherwise it fails with the full attempt table). Under WSL this matters: Windows can reserve a port for Hyper-V, in which case localhost forwarding is never created and the human's browser sees "connection refused" while everything inside the distro works — the fallback then hands you http://<wsl-ip>:6033/ instead. The http / access.url field is authoritative: print it, do not rebuild it. --port pins one port and never jumps (a busy port is an error), --bind loopback|all pins the interface.

Agents get the same guarantee from the MCP side: paintress_viewer ensures the viewer and registers the current project, and the MCP server re-checks it before every write, so the viewer is up before the first edit instead of after someone asks. Its result carries the same url / access block, so an agent that started the viewer on a fallback port tells the human the address that actually works.

A design file that has a sibling Markdown file of the same name (home.ptr → home.md) gets a notes button in the top-left corner of the canvas. Click it and the canvas narrows to make room for the note: what the design is for, what is still open, which requirement it answers. The note is a plain Markdown file next to the design — write it yourself or let the agent write it; the panel is read-only.

The rail in the top-right corner holds the project's design system. Presets are the project's colors, corner radii, spacing and font values: the agent references them ($color-brand) instead of pasting values, and you can change one here and watch the canvas update — no more "a bit bluer". Nodes can also reference a whole preset group; groups are shown read-only in the panel. Components is a read-only gallery of everything reusable the agent has built so far, so you can see progress and the agent can look before rebuilding something that already exists. A font badge next to the version shows how many families loaded; when one is missing its tooltip names the substitute.

Canvas navigation: wheel zooms at the pointer, space / middle button / empty area drags to pan, Ctrl/Cmd+0 returns to 100%, Shift+1 fits the window, and Ctrl/Cmd+K quickly switches design files. Selecting a node opens a read-only inspector. Files with more than one board get a board strip; the active board can be exported as PNG at 0.5x / 1x / 2x (1x means its design pixels; the file is <design>-<board>@<scale>x.png and is scaled back when either edge exceeds 8192px). Edits made through the CLI or MCP are highlighted in the viewer, and clicks assign short ids that the agent can read back with paintress_marks; each mark carries the file and node id, so a shorthand resolves to one element in one file.

Projects are named after their directory path (c-thun/raybend), so the URL reads like the path: http://localhost:6033/c-thun/raybend?file=design/editor.pen. Project rows have an × on hover that unbinds the project (design files are untouched; an agent re-registers on its next start), and Stop server in the sidebar footer shuts the viewer process down — both ask for confirmation first.

The viewer follows the agent instead of asking you to manage it. When an agent starts the viewer it opens your browser on that agent's own project — nothing for the agent to run twice, nothing for you to open by hand; projects appear and leave with a short animation as agents come and go. When the last project is gone or the server is stopped (the sidebar's Stop server, an idle exit), the page counts down ten seconds and closes its own window — you never have to close the tab by hand. A browser that nobody is looking at no longer keeps the process alive.

When npm has a newer release than the running one, the version badge in the header grows a second line in rust red; clicking it opens the upgrade prompt (one copyable sentence) and the GitHub link. The check is client-optional on the daemon side: if npm is unreachable, the badge simply stays as it is.

The toolbar's right side has two viewer-only controls. Canvas background switches Light / Gray / Dark for the design surface without touching the rest of the UI. Language switches the interface between 中文 and EN; on first load it follows the browser, and anything that is not Chinese gets English. Both are per-browser and remembered locally. Registering a project, or dropping a new design file into a watched directory, updates every open viewer without a reload.

Design system

One source of truth per project, so a change lands everywhere instead of on one screen:

  • Tokens live in __preset.ptr and are referenced as $color-brand — never pasted. Kinds: color, radius, spacing, fontSize, font.

  • Preset groups apply a set of token references to one node type; a node opts in with preset: "card".

  • Components live in __components.ptr; the agent copies one in, so a design is not rebuilt from scratch.

  • Fonts are registered per family with a source (web CSS URL, a project css/file, a system font, or bundle for app-only fonts) and, when the source cannot be verified, a design-time preview. Every read reports which families loaded and which fell back.

paintress_preset seed (dry-run by default) fills a coherent starter scale — 27 tokens, 6 preset groups and the two web fonts. audit finds drift, establish proposes tokens from repeated values, and adjust shows the blast radius before changing anything.

Environment variables

Variable

Effect

PTR_BROWSER

Browser executable used for screenshots and PNG export

PAINTRESS_HOME

State directory (daemon registry, Chromium font cache); default ~/.paintress

PAINTRESS_NO_OPEN

1 never opens a browser window

PAINTRESS_NO_AUTO_WEB

1 stops the MCP server from ensuring the viewer before writes

PAINTRESS_NO_WEB_FONTS

1 skips the built-in web fonts (offline / CI)

PAINTRESS_PORT

Port the ui/ vite dev server proxies to (default 6033); set it to the viewer's actual port when the port ladder jumped

CI

true behaves like PAINTRESS_NO_OPEN

MCP clients

paintress install writes these; the same entries can be added by hand.

Client

Config file

Top-level key

Claude Desktop

~/.config/Claude/claude_desktop_config.json

mcpServers

Cursor

~/.cursor/mcp.json

mcpServers

VS Code

~/.config/Code/User/mcp.json

servers (with "type": "stdio")

Windsurf

~/.codeium/windsurf/mcp_config.json

mcpServers

Codex

~/.codex/config.toml

[mcp_servers.paintress]

pi

~/.pi/agent/mcp.json

mcpServers

OpenCode

~/.config/opencode/opencode.json

mcp.servers (current) or mcp (older; command is an array)

paintress mcp-config cursor   # print the exact snippet instead of editing files

Skill

skills/paintress/SKILL.md is a short instruction file for agents: when to reach for these tools, to bring the viewer up before drawing (idempotently), how #1 markers map to node ids, and which tool to use for what. Copy it into your agent's skill directory if it supports one.

Documentation

  • specs/PLAN.md — roadmap and open questions

  • format/spec.yaml — the design file format spec

  • format/README.md — how the format layers relate

  • .agents/memory/ARCHITECTURE.md — design decisions and their rationale

  • .agents/implementations/ — per-change records with measurements

paintress also opens existing .pen design files as-is; paintress convert turns one into .ptr when you ask for it.

Release (maintainers)

Publishing is tag-driven: a v* tag makes .github/workflows/publish.yml first check that ci passed for the same commit, then build, verify the package contents and run npm publish --provenance through OIDC trusted publishing. Tests run once, in ci.yml; publishing does not re-run them. Do not publish from a laptop.

pnpm release patch             # 0.3.1 → 0.3.2
pnpm release minor             # 0.3.1 → 0.4.0
pnpm release major             # 0.3.1 → 1.0.0
pnpm release patch --dry-run   # print the plan only
pnpm release --retag           # after a failed release: move the unpublished tag and re-publish

The script refuses to run on a dirty worktree or a non-default branch, verifies the tag is free, runs typecheck (server + ui), the test suite, the build and the package-contents check, then commits chore(release): vX.Y.Z, tags it, pushes branch + tag, and finally waits until the version is actually on npm (a green run that published nothing is reported as a failure, not a success).

--prepare-only stops after the local commit and tag; --no-wait returns right after the push; --local publishes from this machine as an emergency path and skips the CI checks. --retag is the recovery path after a failed release: once it confirms the version is not on npm yet, it moves the existing tag to the current commit and re-publishes under the same version number; an already published version is refused.

License

MIT


Installation guide for AI agents

You are an agent asked to install paintress on this machine. Work through the steps in order and report what you found, what you reused, and what you changed.

Detection comes first. Several agents can share one machine. A previous agent may already have installed paintress globally and registered it for itself. Installing a second copy is a bug, not thoroughness.

0. Detect

Check

Command

What it tells you

Binary on PATH

command -v paintress

a usable install already exists

Global npm package

npm ls -g --depth=0 paintress

installed globally via npm

Project-local

npm ls --depth=0 paintress

installed inside the current project

Client configs

paintress doctor

which agents already have an entry, and its state

Rules:

  • Any hit means reuse. Do not install again; go to step 2.

  • Report the resolved path and version: paintress --version prints the package version (or npm ls -g --depth=0 paintress).

  • Only when every check is empty do you install (step 1).

If the install succeeded but command -v paintress still finds nothing (some version managers need a new shell), call it by full path — do not install a second copy:

"$(npm prefix -g)/bin/paintress" doctor

1. Install (only if step 0 found nothing)

npm install -g paintress

If global installs are not permitted in this environment:

npm install paintress          # project-local; call it through npx paintress ...
npx -y paintress@latest ...    # no install at all; slower on first run

Prefer the global install. It is what makes the entry in every client config reusable by the next agent.

2. Register the MCP server for the agent you are running in

paintress doctor                    # list detected clients and their state
paintress install --dry-run         # preview the writes
paintress install <client-id>       # write only the client you are running in

Client ids: claude, cursor, vscode, windsurf, codex, pi, opencode. Use paintress install without arguments to cover every detected client.

OpenCode has two config layouts in the wild. install follows whatever the existing file already uses and falls back to the current mcp.servers shape for a new file; force it with --opencode-layout legacy or --opencode-layout v2.

What the write does:

  • adds or refreshes one entry named paintress (mcpServers.paintress, or servers.paintress for VS Code, or [mcp_servers.paintress] for Codex);

  • leaves every other key, server and comment structure in the file alone;

  • writes *.bak-<timestamp> next to the file before replacing it;

  • is idempotent: an identical entry reports noop and nothing is written;

  • uses the bare command paintress when it resolves on PATH, otherwise the absolute path of the binary.

If your client is not in that list

The entry is small and nearly the same everywhere, so adapt it by hand:

  1. Find where the client keeps its MCP servers — its own docs, an /mcp command, or a "configure MCP servers" menu item.

  2. Match the shape. Most clients use a mcpServers object holding command + args; VS Code uses servers with "type": "stdio"; OpenCode puts a single command array under mcp.servers (older builds: under mcp) with "type": "local"; Codex uses a TOML table.

  3. Print the closest snippet and edit it:

paintress mcp-config cursor     # JSON with mcpServers
paintress mcp-config vscode     # JSON with servers + type: stdio
paintress mcp-config opencode   # JSON with mcp.servers + command array
paintress mcp-config codex      # TOML table

To make a client first-class (so doctor and install cover it), add one spec to src/integrations/clients.ts — id, label, format, rootPath, optional typeValue / commandForm / extraFields, and configPath(home, platform, env) — plus one test in test/integrations.spec.ts. No other file needs to change.

mkdir -p <your-skill-dir>/paintress
cp "$(npm root -g)/paintress/skills/paintress/SKILL.md" <your-skill-dir>/paintress/SKILL.md

Use the skill directory your harness actually reads (~/.pi/agent/skills/, ~/.claude/skills/, .cursor/skills/, …). If your harness has no skill mechanism, load the file into context once and keep the tool list.

4. Verify

paintress doctor                                        # entry present, command resolvable
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}\n' | paintress mcp

The second command must answer with a result containing "serverInfo": {"name": "paintress", …}. After a session restart, paintress_doc_info on any design file is the end-to-end check.

5. Multi-agent rules

  • One global install serves every agent on the machine. Do not create per-agent copies.

  • Each agent adds its own config entry. Never rewrite another agent's file, and never remove entries you did not add.

  • If doctor reports noop, another agent already registered it correctly — stop there and say so.

  • Report the outcome as: reused / installed / registered (which client) / skipped (why).

6. Uninstall

npm uninstall -g paintress

Then delete the paintress entry from each client config, or restore the newest *.bak-<timestamp> next to it.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to control pen plotters via MCP tools for text layout, SVG/DXF import, G-code generation, device control, and vision calibration.
      16
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables agents to create and manipulate 3D CAD models using natural language via MCP, with git-based versioning and manufacturing output generation.
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to directly view, understand, and modify local Sketch/Figma design files, including writing code, applying semantic edits, and exporting assets, all through a local MCP server without uploading data.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI clients to execute editable-3D design programs, inspect their geometry, and replay or revise native project files through MCP tools.
      1
      Apache 2.0