Artisign

Artisign

An artificial artisan for UI design: agents build screens, a design system keeps them consistent.

Local-first UX design tool for AI agents. Agents design through MCP, the human reviews in the browser, state lives in plain files.

One Node process on 127.0.0.1. No database, no accounts, no hosting.

Status: Stable (2.2.0) — CLI, store, parser/model, the 25-tool MCP surface, browser preview with live reload/flows/comments, screen variants with side-by-side compare, the design system (tokens, variants, drift warnings, promote_to_system), and packaging are all implemented. Artisign designs its own browser preview — see Designed with itself.

Why

1. Consistency across screens — the design system is first-class; screens store refs, never inline values
2. Token efficiency — tiered reads, field selection, diff mode on writes
3. Flows as first-class — click routes are data, not documentation
4. Render determinism — the preview renders the source, so preview equals output by construction

Install

Requirements. Node.js ≥ 22.4 on macOS or Linux — Windows is not supported (the store's atomic writes and path handling have never been verified there, so package.json makes npm install refuse the platform). For screenshots, a browser that is already installed: Chrome, Edge, Brave, Chromium or Firefox — see Screenshots below.

npm install -g artisign

artisign

1. npm install -g artisign — once.
2. artisign — starts Artisign's background process (the *daemon*), opens the preview in your browser and, on first run, offers to connect your AI tool. After connecting, quit and reopen the AI tool so it picks up the new entry.
3. Ask your AI tool to create or open a project: *"Create an Artisign project in ~/work/acme"*. The project folder (and any missing parent folders) is created for you; the AI tool passes an absolute path, since Artisign does not expand ~ itself. Writes are committed to git automatically (autoCommit, on by default) — Artisign runs git init in the project on the first write, needs git installed for that, and skips the commit rather than fail when it is missing or the folder sits inside another repo. No git identity is required: on a machine where git has no user.name/user.email, Artisign's commits are made as Artisign ; an identity you have configured (git config, or GIT_AUTHOR_*/GIT_COMMITTER_* in the environment) is used as it is, and Artisign never writes to your git config.

Check it works. Ask your AI tool *"List my Artisign projects"* — it calls list_projects and the project you just created appears, and in the preview's project picker too.

Two copies, one version. The global install is the artisign command you type. Your AI tool's entry runs the same version, pinned, through npx (downloaded once on its first launch) as a small stdio bridge; artisign update keeps the two in step. Whichever starts first — you with artisign, or the bridge when your AI tool connects — starts the daemon; both use the same ~/.artisign and port, so there is only ever one. The daemon inherits the environment of the process that started it: to make a variable such as ARTISIGN_BROWSER stick, run artisign from your shell before your AI tool does (artisign stop first if it is already running); putting it in the entry's env also works, but artisign setup rewrites entries, so add it again after an update.

Updating. Run artisign update (also artisign --update). It installs the latest version with npm install -g artisign@latest, re-pins the artisign entries in your AI tools to it and restarts a running Artisign of an older version with its open projects. Then quit and reopen your AI tool, so it launches the re-pinned entry. It does nothing when you are already on the latest version, and never uses sudo. Nothing is updated automatically: artisign checks the npm registry for a newer release at most once a day and prints one line (New version x.y.z — run artisign update) when there is one. Set ARTISIGN_NO_UPDATE_CHECK=1 to turn that off.

Troubleshooting.

• `EACCES` on `npm install -g` — npm cannot write to its global folder. Never fix this with sudo. Use a Node you own (for example through nvm), or point npm at a folder in your home: npm config set prefix ~/.npm-global, then add ~/.npm-global/bin to your PATH.
• nvm — a global install belongs to one Node version. After switching versions, run npm install -g artisign and artisign setup again.
• pnpm, bun or yarn — install with pnpm add -g artisign, bun add -g artisign or yarn global add artisign; update with the same command and @latest (artisign update only *prints* that command for these installs, it does not run it). Then run artisign setup to connect your AI tool and re-pin its entries.

Screenshots. get_screenshot and inspect_node render in a real browser — one that is already on your machine. Artisign finds Chrome, Edge, Brave, Chromium or Firefox by itself (in that order) and drives it headless through the browser's own remote protocol: the Chrome DevTools Protocol for the Chromium family, WebDriver BiDi for Firefox. Nothing to install, no Playwright, no browser download.

• Pick a browser explicitly with ARTISIGN_BROWSER=/path/to/browser in the environment of the process that runs the daemon. The name decides the protocol: a path containing firefox is driven over BiDi, anything else over CDP.
• Cross-browser check. Both tools take an optional browser input ("chrome", "edge", "brave", "chromium", "firefox"), and every result names the browser and version that rendered it — so an agent can check the same screen in a second installed browser before calling it done.
• Each launch uses a fresh, throwaway profile in ~/artisign-browser-profiles/, removed when the browser closes. It lives under your home directory, not /tmp, because a Snap- or Flatpak-packaged Firefox cannot see /tmp.
• No browser installed (a bare server or container): both tools fail with the fix in the error message; every other tool works without one. Installing chromium or firefox-esr from the distribution's packages is enough.

Privacy. Artisign collects nothing — no telemetry, no account, no server beyond the local one it runs. These requests reach the network, none of them about you, and that is the complete list: the update check (at most once a day) asks registry.npmjs.org for the latest version and sends nothing else; artisign update runs npm, and the npx in your AI tool's entry fetches the pinned version from npm, both talking to the npm registry; and the first render of a project in each Artisign run (and again when its typography tokens change) fetches the font families named in your tokens — plus the Material Symbols Rounded icon font, always (a copy shipped with the package is the fallback when that fails) — from Google Fonts, then caches them locally (see Fonts & icons). A remote https:// URL that a screen's own HTML references (an image, a stylesheet) is loaded by the browser that renders it, like any web page. Everything else stays on 127.0.0.1.

Quickstart

artisign on its own is artisign start. It starts the background process, opens http://127.0.0.1: / in your browser once it is healthy — also when it was already running — and, the first time, offers (once, in a terminal and outside CI) to connect the AI tools it finds. Answering no is remembered; artisign setup works any time. Pass --no-open (or set ARTISIGN_NO_OPEN=1) to skip the browser; it is skipped anyway when CI is set or stdout is not a terminal, and when no browser can be opened the URL is printed and that is all. serve, mcp, status, stop and init never open a browser.

Then ask your AI tool for a project. Or do it yourself:

artisign init ./my-project    # scaffold an empty project

artisign start ./my-project # start (or reuse) the background process with it open artisign status # pid, port, open projects

The remaining commands, for reference — this block is a catalogue, not a sequence:

artisign serve ./my-project   # foreground (development); opens the project on start

artisign stop # stop the background process artisign help [command] # also: artisign --help

Artisign is multi-project: one process on 127.0.0.1:4711 holds several projects open at once. Open or create projects from the browser UI (project picker in the topbar), or let agents address any project by name or path in the project input of each tool call — list_projects shows the names. No restart when you switch.

Advanced

Connecting an AI tool. artisign setup connects Claude Code, Claude Desktop, Cursor, Codex CLI, VS Code and opencode. For each one it finds, it asks, then writes a user-level entry named artisign that runs npx -y artisign@ mcp, pinned to the version that ran setup; other entries and settings are left untouched. Claude Code is driven through its own claude mcp CLI and Codex CLI through codex mcp add/remove (it honours CODEX_HOME) when those are on your PATH; GUI clients (Claude Desktop, Cursor, VS Code) get the npx found on your PATH, as an absolute path, because they do not inherit your shell's. A config file that holds comments or trailing commas is never rewritten — setup prints the entry to add by hand instead — and a symlinked config is written through. --yes connects every tool found without asking (the only way to run without a terminal); artisign setup --remove removes exactly the artisign entries. Run it again after an update to re-pin (artisign update does so for you). Quit and reopen the AI tool after setup, so it picks up the entry.

Manual entry. If you don't run setup, add the same stdio server to your AI tool by hand, pinned to the version you installed (artisign --version). A terminal client (Claude Code, Codex CLI, opencode) can use plain npx:

claude mcp add --scope user --transport stdio artisign -- npx -y artisign@<version> mcp

A GUI client (Claude Desktop, Cursor, VS Code) does not inherit your shell's PATH, so give it the absolute path of your npx (which npx) and a PATH that starts with its directory — this is what setup writes. For Claude Desktop, in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{

"mcpServers": { "artisign": { "command": "/opt/homebrew/bin/npx", "args": ["-y", "artisign@ ", "mcp"], "env": { "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin" } } } }

Replace /opt/homebrew/bin with the directory which npx shows. Quit and reopen the client afterwards.

artisign mcp is a stdio bridge: it forwards every MCP message to the running background process and starts it if it is not running, so it is the same backend whichever client connects. It takes no project directory — the project is named in each tool call.

State and ports. The port comes from ~/.artisign/config.json or --port N on start and serve (a settings.port in a project's artisign.json is deprecated and ignored). Daemon-level state — that config plus the daemon.lock holding the running pid and port — lives in ~/.artisign. Set ARTISIGN_HOME to move it somewhere else; that, together with --port, is what lets a second daemon run fully isolated from the first, which is worth doing before you try anything destructive against projects you care about.

Just trying it. npx artisign runs it once without installing.

The 25 tools

Every tool except list_projects, init_project and get_guide takes a required project input: a known project's name (as list_projects returns it) or an absol