Skip to content
Back to search

sketchy

SkillWorks with Claude CodeGitHub

A layout engine for AI diagrams: the model says what to draw, Sketchy figures out where. Hand-drawn, interactive, in Claude, Cursor and VS Code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ddkbs/sketchy with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ddkbs/sketchy'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ddkbs--sketchy/badge.svg)](/listings/ddkbs--sketchy)

HTML

<a href="/listings/ddkbs--sketchy"><img src="/api/listings/ddkbs--sketchy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://github.com/ddkbs/sketchy/releases/latest). 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](https://www.jsdelivr.com), 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](https://developer.mozilla.org/docs/Web/Security/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](https://github.com/ddkbs/sketchy/releases/latest) (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:

| Model | Download | Memory | Notes | | ------ | -------- | ------- | ----------------------------------------- | | Small | ~280 MB | ~1 GB | Recommended. Printed text, distinct parts | | Medium | ~830 MB | ~2.5 GB | Better grounding of small parts | | Large | ~3.1 GB | ~4.5 GB | Most precise |

Claude Code in the terminal

Sketchy is on npm as [`@ddkbs/sketchy`](https://www.npmjs.com/package/@ddkbs/sketchy). With [Node.js](https://nodejs.org) 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](https://nodejs.org) 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](https://github.com/modelcontextprotocol/ext-apps) inline, Sketchy saves each drawing as an interactive HTML file, as described under [Other MCP clients](#other-mcp-clients).

Cursor and VS Code

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 11 lines
  1. {
  2. "name": "sketchy",
  3. "owner": { "name": "ddkbs" },
  4. "plugins": [
  5. {
  6. "name": "sketchy",
  7. "source": "./claude-code",
  8. "description": "Hand-drawn, interactive diagrams right in the Claude Code terminal."
  9. }
  10. ]
  11. }
README.md · README · 256 lines
  1. # Sketchy
  2. 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](https://modelcontextprotocol.io) server in Claude Code, Codex, Cursor, VS Code and other MCP clients.
  3. 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.
  4. ![Sketchy in a chat: the answer to "What happens when I open a web page?" comes with an interactive drawing and its toolbar (Draw, SVG, PNG, Excalidraw)](docs/images/chat.png)
  5. ## What it can draw
  6. ### Systems, step by step
  7. 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.
  8. ![The life of a web request, from the browser through CDN, load balancer and services to cache, database and queue](docs/images/request.png)
  9. ![Step 5 of the walkthrough: the orders service, cache and database are circled](docs/images/request-step.png)
  10. ### Concepts from computer science and machine learning
  11. Sketchy is not limited to hardware. Structure, flow, comparison and metaphor patterns cover any topic, from transformers to TCP.
  12. ![How an LLM picks the next word: tokenizer, embeddings, a transformer block with self-attention and MLP, and sampling](docs/images/transformer.png)
  13. ### Your own code
  14. 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.
  15. ![Architecture of a repository with nested folders](docs/images/repo.png)
  16. ### Circuits from Arduino and ESP32 sketches
  17. 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](https://github.com/wokwi/wokwi-elements)) and connects pins by name. Sketchy routes the wires and places the callouts.
  18. <table>
  19. <tr>
  20. <td width="58%"><img alt="ESP32 with PIR sensor, DHT22, buzzer and status LED" src="docs/images/esp32.png"></td>
  21. <td width="42%"><img alt="Arduino Uno driving an LED through a resistor" src="docs/images/circuit.png"></td>
  22. </tr>
  23. </table>
  24. ### Labeled photos
  25. The AI finds a freely licensed photo (Wikimedia Commons, Openverse), and a vision model **running on your computer** ([Florence-2](https://huggingface.co/microsoft/Florence-2-base-ft)) locates the parts and printed text to label. Attribution is always shown.
  26. ![Photo of an Arduino Uno with labeled parts](docs/images/photo.jpg)
  27. ### Comparisons and metaphors
  28. <table>
  29. <tr>
  30. <td width="50%"><img alt="SQL vs. NoSQL side by side" src="docs/images/comparison.png"></td>
  31. <td width="50%"><img alt="CPU caches explained as a kitchen" src="docs/images/metaphor.png"></td>
  32. </tr>
  33. </table>
  34. ### Interactive, exportable
  35. - **Hover** any box, pin or wire for details.
  36. - **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.
  37. - **Click** a code node to open the file, or a photo credit to open its source.
  38. - **Export** as **SVG** or **PNG**, fonts included, or as an **Excalidraw** file to keep editing on [excalidraw.com](https://excalidraw.com): your system's save dialog asks where to put the file.
  39. - **Fullscreen** where the host supports it.
  40. ![Drawing mode: the CDN is circled in red pen with a note, and a question is ready to send to the AI](docs/images/draw.png)
  41. ## Install
  42. Where do you work? Sketchy comes two ways, and both can be installed side by side:
  43. - **In the chat** (Claude on web, desktop and the iPhone and Android apps): the skill. Nothing to install locally.
  44. - **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.
  45. ### Claude chat (web, desktop and mobile)
  46. The skill draws right in the chat, with no server:
  47. 1. Download `sketchy-skill-<version>.zip` from the [latest release](https://github.com/ddkbs/sketchy/releases/latest).
  48. 2. In Claude, open **Settings → Capabilities → Skills** and upload the zip.
  49. 3. Ask for a drawing in any chat.
  50. **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.
  51. Claude writes the scene, and the chat's inline visualization loads Sketchy's browser bundle from [jsDelivr](https://www.jsdelivr.com), 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](https://developer.mozilla.org/docs/Web/Security/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.
  52. ### Claude desktop app (Code tab)
  53. 1. Download the `.mcpb` file for your platform from the [latest release](https://github.com/ddkbs/sketchy/releases/latest) (macOS on Apple Silicon, Windows or Linux).
  54. 2. Double-click it (or drag it into **Settings → Extensions**) and confirm.
  55. 3. Optional: in the extension settings choose your editor and where Sketchy stores its data.
  56. 4. Open the **Code** tab and start a session. Drawings appear inline next to Claude's answer.
  57. The **Chat** tab does not display views from locally installed extensions; use the skill above there.
  58. 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:
  59. | Model | Download | Memory | Notes |
  60. | ------ | -------- | ------- | ----------------------------------------- |
  61. | Small | ~280 MB | ~1 GB | Recommended. Printed text, distinct parts |
  62. | Medium | ~830 MB | ~2.5 GB | Better grounding of small parts |
  63. | Large | ~3.1 GB | ~4.5 GB | Most precise |
  64. ### Claude Code in the terminal
  65. Sketchy is on npm as [`@ddkbs/sketchy`](https://www.npmjs.com/package/@ddkbs/sketchy). With [Node.js](https://nodejs.org) 20 or newer, register it once for all your projects:
  66. ```bash
  67. claude mcp add sketchy --scope user -- npx -y @ddkbs/sketchy
  68. ```
  69. 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.
  70. ### Codex
  71. With [Node.js](https://nodejs.org) 20 or newer, register Sketchy once for the Codex CLI and IDE extension:
  72. ```bash
  73. codex mcp add sketchy -- npx -y @ddkbs/sketchy
  74. ```
  75. 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`:
  76. ```toml
  77. [mcp_servers.sketchy]
  78. command = "npx"
  79. args = ["-y", "@ddkbs/sketchy"]
  80. ```
  81. Where Codex cannot show [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) inline, Sketchy saves each drawing as an interactive HTML file, as described under [Other MCP clients](#other-mcp-clients).
  82. ### Cursor and VS Code
  83. Both show Sketchy's drawings inline in the agent chat. With Node.js installed, click **[Add to Cursor](https://cursor.com/en/install-mcp?name=sketchy&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBkZGticy9za2V0Y2h5Il0sImVudiI6eyJTS0VUQ0hZX0VESVRPUiI6ImN1cnNvciJ9fQ%3D%3D)** or **[Add to VS Code](https://vscode.dev/redirect/mcp/install?name=sketchy&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40ddkbs%2Fsketchy%22%5D%7D)** and confirm.
  84. To add it by hand, put this into `~/.cursor/mcp.json` (Cursor, all projects) or your VS Code MCP settings:
  85. ```json
  86. {
  87. "mcpServers": {
  88. "sketchy": {
  89. "command": "npx",
  90. "args": ["-y", "@ddkbs/sketchy"],
  91. "env": { "SKETCHY_EDITOR": "cursor" }
  92. }
  93. }
  94. }
  95. ```
  96. `SKETCHY_EDITOR` decides which editor opens when you click a box in a drawing; leave it out for VS Code.
  97. ### Other MCP clients
  98. Sketchy is a standard MCP server and works in any client that supports [MCP Apps](https://github.com/modelcontextprotocol/ext-apps). Start it with `npx -y @ddkbs/sketchy`, as above.
  99. 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.
  100. 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.
  101. ## Try it
  102. - _"What happens when I open a web page? Walk me through it."_
  103. - _"How does an LLM pick the next word?"_
  104. - _"Explain the architecture of /path/to/my/repo, then walk me through one request."_
  105. - _"How is this sketch wired?"_ followed by your `.ino` file
  106. - _"Show me a photo of a Raspberry Pi and label the ports."_
  107. - _"Compare TCP and UDP."_
  108. - _"Explain CPU caches with an everyday metaphor."_
  109. The same patterns are available as prompts: `explain-structure`, `explain-flow`, `compare`, `metaphor`, `explain-repo` and `explain-circuit`.
  110. ## How it works
  111. ```
  112. The AI describes the scene (extension: tools like sketch, place_part, label;
  113. skill: the same scene as JSON in an inline widget)
  114. ↓
  115. Scene: nodes, groups, parts, wires, labels, photos, steps — no coordinates
  116. ↓
  117. Layout engine (elkjs): positions, orthogonal routing, collision-free callouts
  118. ↓
  119. Viewer: hand-drawn rendering with rough.js, hover, steps, export
  120. ```
  121. 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.
  122. <details>
  123. <summary>Tools</summary>
  124. | Tool | Purpose |
  125. | -------------------------------------- | ---------------------------------------------------------- |
  126. | `sketch` | Draw a whole scene in one call, in the compact line syntax |
  127. | `search_parts` | Electronic part types and their pins |
  128. | `find_image`, `locate`, `choose_model` | Photo search, local grounding, model setup |
  129. 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`, …).
  130. </details>
  131. ### Follow-ups
  132. 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.
  133. ## Token usage
  134. 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.
  135. | Average per answer, fresh conversation | Plain text | Sketchy, JSON (≤ 0.1.5) | Sketchy, compact (0.1.6) |
  136. | -------------------------------------- | ---------- | ----------------------- | ------------------------ |
  137. | Output tokens (what Claude writes) | 962 | 1,168 | **686** (−29% vs. text) |
  138. | Tool definitions | – | ~4,100 | **~500** |
  139. | Cost on Sonnet list prices | ~$0.034 | ~$0.059 | ~$0.043 |
  140. 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:
  141. | Answers in the session | Plain text | Sketchy, JSON | Sketchy, compact |
  142. | ---------------------- | ---------- | ------------- | ---------------- |
  143. | 1 | $0.04 | $0.07 | $0.05 |
  144. | 3 | $0.21 | $0.27 | **$0.20** |
  145. | 6 | $0.61 | $0.75 | **$0.58** |
  146. - **Claude writes less for a drawing than for text.** Layout and drawing happen in Sketchy and cost no tokens.
  147. - **Every answer stays in the history.** Shorter answers keep it small, so each follow-up question costs less than after a text answer.
  148. - **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.
  149. Measured on November 2, 2026 in Claude Code with an empty project. Run it yourself with `npm run build && node scripts/token-benchmark.mjs`.
  150. ## Configuration
  151. | Variable | Default | Description |
  152. | -------------------- | ------------- | --------------------------------------------------------------------------------- |
  153. | `SKETCHY_EDITOR` | `vscode` | Editor for file links: `vscode`, `cursor`, `windsurf`, `vscode-insiders`, `zed` |
  154. | `SKETCHY_PHOTOS` | `on` | `off` disables photo search and labeling |
  155. | `SKETCHY_DATA_DIR` | `~/.sketchy` | Models, cached photos and the local SQLite database |
  156. | `SKETCHY_EXPORT_DIR` | `~/Downloads` | Folder the save dialog opens in, and where exports go when no dialog is available |
  157. | `SKETCHY_FORMAT` | `compact` | `json` restores the JSON scene tools of earlier versions |
  158. | `SKETCHY_OPEN` | off | `1` opens drawings in the browser in clients without MCP Apps |
  159. ## Development
  160. Requires Node.js 20 or later.
  161. ```bash
  162. npm install
  163. npm run build # part catalog, server and viewer
  164. npm test
  165. npm run preview # viewer with sample scenes at http://localhost:5173/preview.html
  166. npm run pack # .mcpb bundle for the current platform
  167. npm run build:skill # chat skill zip
  168. npm run build:web # browser bundle that the skill loads
  169. ```
  170. See [CONTRIBUTING.md](CONTRIBUTING.md) for the project layout.
  171. ## License
  172. [MIT](LICENSE) © ddkbs. Sketchy builds on open-source work listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.