Sketchy

Sketchy lets your AI assistant draw while it explains: clean, hand-drawn, interactive diagrams rendered right next to the answer. It works in the Claude chat as a skill, including the Claude app on your phone, and as an MCP server in Claude Code, Codex, Cursor, VS Code and other MCP clients.

The AI decides what to draw and label. Sketchy decides where: a part library with named anchor points and automatic layout. The AI never computes coordinates, so drawings come out precise and consistent every time.

What it can draw

Systems, step by step

Ask "What happens when I open a web page?" and the AI draws the whole path, then walks you through it. Each step circles what matters in red pen and fades the rest. Use the buttons or the arrow keys.

Concepts from computer science and machine learning

Sketchy is not limited to hardware. Structure, flow, comparison and metaphor patterns cover any topic, from transformers to TCP.

Your own code

Ask "Explain my repo". The AI reads the code and draws modules, folders and data flow. Click a box to open the file in VS Code, Cursor, Windsurf or Zed; hover to see what it does.

Circuits from Arduino and ESP32 sketches

Ask "How is my sketch wired?". The AI reads pinMode, digitalWrite and friends, places real parts (50 boards, sensors, displays and modules from wokwi-elements) and connects pins by name. Sketchy routes the wires and places the callouts.

Labeled photos

The AI finds a freely licensed photo (Wikimedia Commons, Openverse), and a vision model running on your computer (Florence-2) locates the parts and printed text to label. Attribution is always shown.

Comparisons and metaphors

Interactive, exportable

• Hover any box, pin or wire for details.

• Draw on the sketch with a red pen, a highlighter and notes, then Send to AI with a question: the AI gets the marked-up drawing and which parts you marked.

• Click a code node to open the file, or a photo credit to open its source.

• Export as SVG or PNG, fonts included, or as an Excalidraw file to keep editing on excalidraw.com: your system's save dialog asks where to put the file.

• Fullscreen where the host supports it.

Related MCP server: Excalidraw Architect MCP

Install

Where do you work? Sketchy comes two ways, and both can be installed side by side:

• In the chat (Claude on web, desktop and the iPhone and Android apps): the skill. Nothing to install locally.

• While coding (Claude Code in the desktop app or terminal, Codex, Cursor, VS Code): the extension, which adds photo labeling, SVG, PNG and Excalidraw export and click-to-open files.

Claude chat (web, desktop and mobile)

The skill draws right in the chat, with no server:

1. Download sketchy-skill-<version>.zip from the latest release.

2. In Claude, open Settings → Capabilities → Skills and upload the zip.

3. Ask for a drawing in any chat.

On your phone: skills belong to your Claude account, so once uploaded the skill also works in the Claude app on iPhone and Android. Ask a question on the go and the drawing appears in the chat, with steps you can tap through. Nothing to install on the phone.

Claude writes the scene, and the chat's inline visualization loads Sketchy's browser bundle from jsDelivr, which serves it from this repository's cdn branch. The skill follows the current minor version, so it picks up fixes without being uploaded again. To run exactly the code you reviewed, use sketchy-skill-<version>-pinned.zip instead: it loads the bundle from a fixed commit of the cdn branch and checks it with a Subresource Integrity hash, so the browser refuses any other file. It does not pick up fixes; upload the next pinned zip to update. Photo labeling and opening files from a drawing need your computer, so they stay in the desktop extension.

Claude desktop app (Code tab)

1. Download the .mcpb file for your platform from the latest release (macOS on Apple Silicon, Windows or Linux).

2. Double-click it (or drag it into Settings → Extensions) and confirm.

3. Optional: in the extension settings choose your editor and where Sketchy stores its data.

4. Open the Code tab and start a session. Drawings appear inline next to Claude's answer.

The Chat tab does not display views from locally installed extensions; use the skill above there.

The photo-labeling model is not part of the download. The first time the AI labels a photo, Sketchy asks you to pick a model size:

Claude Code in the terminal

Sketchy is on npm as @ddkbs/sketchy. With Node.js 20 or newer, register it once for all your projects:

claude mcp add sketchy --scope user -- npx -y @ddkbs/sketchy

Run claude mcp list to check that it is connected. npx downloads the server on first start and picks up new versions on its own.

Codex

With Node.js 20 or newer, register Sketchy once for the Codex CLI and IDE extension:

codex mcp add sketchy -- npx -y @ddkbs/sketchy

Run codex mcp list to check that it is enabled, then start a new session. To add it by hand, put this into ~/.codex/config.toml:

[mcp_servers.sketchy]
command = "npx"
args = ["-y", "@ddkbs/sketchy"]

Where Codex cannot show MCP Apps inline, Sketchy saves each drawing as an interactive HTML file, as described under Other MCP clients.

Cursor and VS Code

Both show Sketchy's drawings inline in the agent chat. With Node.js installed, click Add to Cursor or Add to VS Code and confirm.

To add it by hand, put this into ~/.cursor/mcp.json (Cursor, all projects) or your VS Code MCP settings:

{
  "mcpServers": {
    "sketchy": {
      "command": "npx",
      "args": ["-y", "@ddkbs/sketchy"],
      "env": { "SKETCHY_EDITOR": "cursor" }
    }
  }
}

SKETCHY_EDITOR decides which editor opens when you click a box in a drawing; leave it out for VS Code.

Other MCP clients

Sketchy is a standard MCP server and works in any client that supports MCP Apps. Start it with npx -y @ddkbs/sketchy, as above.

Clients without MCP Apps (OpenCode, for example) cannot show drawings inline. There Sketchy saves each drawing as an interactive HTML file in ~/.sketchy/exports/, tells the AI where it is, and asks it to explain the diagram fully in text. Set SKETCHY_OPEN=1 to open the file in your browser right away.

The npm package leaves out the photo-labeling runtime (about 470 MB) so it starts quickly. Sketchy installs it with npm into its data folder the first time you pick a model; the desktop extension ships it.

Try it

• "What happens when I open a web page? Walk me through it."

• "How does an LLM pick the next word?"

• "Explain the architecture of /path/to/my/repo, then walk me through one request."

• "How is this sketch wired?" followed by your .ino file

• "Show me a photo of a Raspberry Pi and label the ports."

• "Compare TCP and UDP."

• "Explain CPU caches with an everyday metaphor."

The same patterns are available as prompts: explain-structure, explain-flow, compare, metaphor, explain-repo and explain-circuit.

How it works

The AI describes the scene (extension: tools like sketch, place_part, label;
                            skill: the same scene as JSON in an inline widget)
          ↓
Scene: nodes, groups, parts, wires, labels, photos, steps — no coordinates
          ↓
Layout engine (elkjs): positions, orthogonal routing, collision-free callouts
          ↓
Viewer: hand-drawn rendering with rough.js, hover, steps, export

Every feature fills the same scene, and a single viewer renders it. The visual style lives in the renderer, so every drawing looks consistent no matter what the AI asks for. The extension runs layout in its server process and shows the viewer as an MCP App; the skill runs the same code in the browser from a bundle on jsDelivr.

A scene is a few short lines: browser Browser @globe, browser -> server HTTPS, step Request: The browser asks | browser browser->server. Setting SKETCHY_FORMAT=json restores the JSON sketch tool and the incremental tools of earlier versions (add_node, add_edge, place_part, label, render, …).

Follow-ups

Ask the AI to change a drawing ("add the cache and the call back to the router") and it sends the scene again with the same ids. Sketchy keeps the order and places of everything the earlier drawing already showed and fits the new parts in around them, so before and after stay comparable, also when a back-edge closes a cycle.

Token usage

Does a drawing cost more than a text answer? We asked Claude Sonnet to explain five topics (DNS, git branches, transformers, the TLS handshake, an Arduino button circuit), in plain text and with Sketchy, and read the exact usage Claude Code reports. Version 0.1.6 introduced the compact scene format; the JSON column is the format before it.

Over a whole session the compact format is cheaper than plain text. Six questions in a row, each variant in its own session, mean of two runs:

• Claude writes less for a drawing than for text. Layout and drawing happen in Sketchy and cost no tokens.

• Every answer stays in the history. Shorter answers keep it small, so each follow-up question costs less than after a text answer.

• A tool call adds a turn that re-sends the context, mostly from the cache at a tenth of the price; this is why the very first answer still costs a little more than text.

Measured on November 2, 2026 in Claude Code with an empty project. Run it yourself with npm run build && node scripts/token-benchmark.mjs.

Configuration

Development

Requires Node.js 20 or later.

npm install
npm run build      # part catalog, server and viewer
npm test
npm run preview    # viewer with sample scenes at http://localhost:5173/preview.html
npm run pack       # .mcpb bundle for the current platform
npm run build:skill  # chat skill zip
npm run build:web    # browser bundle that the skill loads

See CONTRIBUTING.md for the project layout.

License

MIT © ddkbs. Sketchy builds on open-source work listed in THIRD_PARTY_NOTICES.md.