# iconwright

Icons that fit where they live. Tell your agent what you want: iconwright finds the artwork, lays out options side by side, shows each one on a real taskbar, desktop and phone, then makes the files, or puts the icon straight onto your Windows taskbar.

- Design loop: search_icons -> design_icons -> preview_icon -> make_icon / app_apply_icon
- Exports: Windows .ico, macOS .icns, favicon and web-app icons, PNGs at every size
- Windows: restyle, pin, unpin and reorder taskbar apps (one Explorer restart per change), arrange desktop icons, undo everything
- Works with Claude Code (plugin + skill + prompts), Codex and any MCP client; design and export also run on macOS and Linux

## Hand this to your agent

```text
Set up iconwright for me (https://iconwright.guptajayam.com). It's an MCP server
for designing icons and customizing the Windows taskbar and desktop.

1. If you are Claude Code, run:
     /plugin marketplace add JayceeGupta/iconwright
     /plugin install iconwright@icon-playground
   Otherwise: git clone https://github.com/JayceeGupta/iconwright, run npm install
   in it, and add a stdio MCP server named "iconwright" that runs:
     node <clone>/bin/iconwright-mcp.mjs
2. Read https://iconwright.guptajayam.com/llms.txt to learn how to use it well.
3. On Windows, call the doctor tool. Then tell me what you can do.
```

Docs: https://iconwright.guptajayam.com/llms.txt


---

# Getting started

iconwright lets you design icons by talking to an AI agent, and put them on your Windows taskbar and desktop. This page gets it installed and walks you through a first icon. It takes about five minutes.

## What you need

- **Node.js 20 or newer.** Check with `node --version`; get it from [nodejs.org](https://nodejs.org).
- **An agent that speaks MCP**: Claude Code, Codex, Cursor, VS Code or similar. You can also use the [command line](cli.md) or the [studio](studio.md) without one.
- **Windows 10 or 11** for the taskbar and desktop features. Designing and exporting icons works on macOS and Linux too.

## Install

### Claude Code

Run these two commands inside Claude Code:

```text
/plugin marketplace add JayceeGupta/iconwright
/plugin install iconwright@icon-playground
```

Restart Claude Code if it asks. You get the MCP tools, a skill that teaches Claude to use them well, and four commands in the `/` menu: design-icon, restyle-taskbar, tidy-desktop and undo-everything.

### Codex

```bash
git clone https://github.com/JayceeGupta/iconwright
cd iconwright && npm install
codex mcp add iconwright -- node "$PWD/bin/iconwright-mcp.mjs"
```

Codex asks before each tool call. To let it run the read-only tools without asking, add them to `~/.codex/config.toml`:

```toml
[mcp_servers.iconwright.tools.search_icons]
approval_mode = "approve"

[mcp_servers.iconwright.tools.design_icons]
approval_mode = "approve"

[mcp_servers.iconwright.tools.preview_icon]
approval_mode = "approve"

[mcp_servers.iconwright.tools.taskbar_status]
approval_mode = "approve"
```

### Any other MCP client

Clone the repository and run `npm install` as above. Add a **stdio** server to your client's MCP settings, with the path to your clone, then restart or reconnect the client:

```json
{
  "mcpServers": {
    "iconwright": { "command": "node", "args": ["C:/path/to/iconwright/bin/iconwright-mcp.mjs"] }
  }
}
```

### Let your agent do it

Copy the [setup prompt](agents.md#setup-prompt) and paste it to your agent. It installs iconwright, reads the usage guide and checks your PC.

## Your first icon

Ask your agent in plain words. For example:

> Design me a calm, minimal icon for a notes app. Show me a few options.

A good agent will:

1. **Search** for artwork and show you a numbered sheet of candidates.
2. **Compare** a few of them in different styles, in one grid. You answer with a cell, like “B2”.
3. **Preview** your pick on a taskbar, desktop and phone, so you can see it at real sizes.
4. **Make the files** you need: `.ico` for Windows, `.icns` for macOS, a favicon set for a website.

Each step is a single small image, so trying another color or shape is cheap. Say what to change (“warmer”, “less padding”, “try a circle”) and it redraws.

Prefer to drag sliders yourself? Ask for the studio (“open this in the studio”), or open [iconwright studio](/studio/) in your browser.

## Your first taskbar change (Windows)

> Make all my taskbar icons white.

The agent reads your pinned apps and restyles each app's own icon in one call. Open windows update right away; a few pinned icons only update after Explorer restarts, and the agent will offer to do that once at the end.

To undo:

> Put my original icons back.

## Check your PC

On Windows, ask the agent to run **doctor**, or run it yourself:

```bash
node bin/iconwright.mjs doctor
```

It checks your Windows and PowerShell versions, the pinned-apps format, your backups and any taskbar mods, and changes nothing.

## Next

- [Design icons](design.md): the design loop, style strings and export formats.
- [Taskbar and apps](taskbar.md): restyling, pinning and reordering.
- [Safety and risks](safety.md): what iconwright changes and how to undo it.
- [For agents](agents.md): how an agent should drive iconwright.


---

# For agents

This page is for AI agents that use iconwright, and for people setting one up. It covers the setup prompt, how to drive the tools well, and where to find machine-readable docs.

## Setup prompt

Paste this to any agent with a terminal (Claude Code, Codex, Cursor and others):

```text
Set up iconwright for me (https://iconwright.guptajayam.com). It's an MCP server
for designing icons and customizing the Windows taskbar and desktop.

1. If you are Claude Code, run:
     /plugin marketplace add JayceeGupta/iconwright
     /plugin install iconwright@icon-playground
   Otherwise: git clone https://github.com/JayceeGupta/iconwright, run npm install
   in it, and add a stdio MCP server named "iconwright" that runs:
     node <clone>/bin/iconwright-mcp.mjs
2. Read https://iconwright.guptajayam.com/llms.txt to learn how to use it well.
3. On Windows, call the doctor tool. Then tell me what you can do.
```

## Docs for machines

- [`/llms.txt`](/llms.txt): a short index of the docs with the key usage rules.
- [`/llms-full.txt`](/llms-full.txt): every docs page in one file.
- Every docs page is also plain Markdown: add `.md` to its address, for example [`/docs/tools.md`](/docs/tools.md).
- The [MCP tool reference](tools.md) is generated from the server's own tool definitions, so it's always current.

In Claude Code, the plugin also installs a skill with these guidelines, so you don't need to fetch anything.

## How to use iconwright well

### Design in rounds of small images

Each design tool returns one small image. Show it to the user and let them choose, then change one thing per round.

1. `search_icons` returns a numbered contact sheet; picture N is `icons[N-1]`. Search two or three phrasings for range.
2. `design_icons` puts sources in rows (A, B, …) and styles in columns (1, 2, …). The user answers with a cell like “B2”.
3. `preview_icon` shows the pick on real surfaces. Do this before applying anything; it catches icons that vanish on a light or dark taskbar.
4. `make_icon` writes files; `app_apply_icon` puts the icon on Windows apps.

When the user wants to fiddle by hand, call `open_studio` with the current source and style. The studio's “Copy for your agent” button gives them text to paste back to you.

### Styles are strings

Every styling argument is one string of `key=value` pairs:

```text
color=white bg=#2d5ba6 shape=squircle shadow
color=#25282d padding=0.12
color=white bg=linear-gradient(135deg,#e9c46a,#c47335) shape=rounded radius=0.3
```

Keys: `color`, `bg`, `shape` (`none`, `square`, `rounded`, `squircle`, `circle`), `radius` (0 to 0.5), `padding` (0 to 0.45), `shadow`. A typo is an error that names the valid keys.

### Sources

- An Iconify id: `mdi:music`, `ph:rocket-launch-fill`. Brand logos: `simple-icons:<brand>`.
- A file: `.svg`, `.png`, `.jpg`, `.webp` or `.ico`.
- Raw SVG text.
- `app:<App name>`: an installed Windows app's current icon. Useful for restyling an app's own artwork.

### Windows: batch, don't loop

- Restyle many apps in **one** `app_apply_icon` call. Source `"app"` restyles each app's own icon: `apps: [all pinned names], source: "app", style: "color=white"`.
- `taskbar_pins` takes `pin`, `unpin` and `order` together and restarts Explorer **once**. Every separate call is another restart, which closes File Explorer windows and can upset taskbar styling tools. Use `dryRun: true` to check the resulting order first.
- If a result includes a `hint` about refreshing, call `taskbar_refresh` once at the end, not after each change.
- Get exact app names from `taskbar_status` or `find_apps`.

### Undo

| To undo | Call |
| --- | --- |
| Icons on some apps or desktop items | `restore_icons` with `apps` or `desktopItems` |
| Every icon iconwright changed | `restore_icons` with `all: true` |
| The latest pin change | `taskbar_restore_backup` (default `"last"`) |
| All pin changes ever | `taskbar_restore_backup` with `from: "original"` |
| Desktop arrangement | `desktop_layout` with `action: "load"` (save one first) |

Tell the user how to undo after any visible change.

### Checking your work

- `capture` takes a screenshot of the taskbar, the desktop icons or the screen. Use it after visible changes.
- `doctor` explains why something failed: Windows version, pin-list format, backups, taskbar mods.

## Prompts

The server offers four prompts. Clients that support MCP prompts show them as commands; in Claude Code they're in the `/` menu, marked (MCP):

| Prompt | What it does |
| --- | --- |
| `design-icon` | Designs an icon from an idea: search, compare, preview, export or apply. |
| `restyle-taskbar` | Gives every pinned app one look, with a preview before applying. |
| `tidy-desktop` | Backs up the desktop layout, then arranges icons. |
| `undo-everything` | Restores every icon and, if wanted, the original pinned apps. |

## Cost

The full tool list is about 4,500 tokens. Typical image results are small: a 24-icon search sheet is about 150 image tokens, a 3 × 4 design grid about 200, and a four-scene preview about 700. Text results are compact JSON with forward-slash paths and no empty fields.


---

# Design icons

iconwright turns icon design into a quick back-and-forth: find artwork, compare looks, see the winner in place, then export it. Every step works on Windows, macOS and Linux.

You can do all of this by asking your agent, from the [studio](studio.md), or with the [command line](cli.md). This page uses agent requests as examples; the tool names are in brackets for reference.

## 1. Find artwork

> Find me some rocket icons.

iconwright searches [Iconify](https://iconify.design): more than 200,000 open-source icons from about 200 sets, including brand logos. You get one sheet with numbered pictures, so you can answer “3, 7 and 12” (`search_icons`).

- Brand logos live in the `simple-icons` set: `simple-icons:spotify`, `simple-icons:github`.
- To stay within one look, ask for a set: “only from Phosphor” (`ph`), “Material Design” (`mdi`), “Lucide” (`lucide`), “Tabler” (`tabler`).
- Licenses are listed with every search. Most sets are MIT, Apache 2.0 or similar; a few ask for attribution (CC BY).

You can also start from your own artwork: an `.svg`, `.png`, `.jpg`, `.webp` or `.ico` file, or SVG code pasted into the chat. On Windows, an installed app's current icon works too: `app:Spotify`.

## 2. Compare looks

> Try 3, 7 and 12 in white, on a blue squircle, and with an orange gradient.

You get one grid: artwork in rows (A, B, C) and styles in columns (1, 2, 3). Every cell shows the icon large and at 24 px on a dark and a light strip, because a design that works at 256 px can fail at taskbar size. Answer with a cell: “B2” (`design_icons`).

Keep rounds small and change one thing at a time: a color, then a shape, then padding.

## 3. See it in place

> Show me B2 on a taskbar and on a phone.

iconwright draws the icon where icons live (`preview_icon`):

| Scene | What it shows |
| --- | --- |
| `taskbar` | A Windows 11 taskbar, dark and light, with the app open and focused |
| `start` | The Start menu's pinned grid, with the app name under the icon |
| `desktop` | Medium and large desktop icons on a wallpaper, one selected |
| `explorer` | A File Explorer window: the title-bar icon and a 16 px list row |
| `browser` | Browser tabs, dark and light, with the icon as a favicon |
| `dock` | The macOS Dock with its hover label |
| `ios` | An iPhone home screen, with the iOS rounded mask applied |
| `android` | An Android launcher with a round mask |
| `sizes` | The icon at true pixel sizes (16 to 48 px), plus 16 and 24 px magnified |

On Windows, the taskbar and Start scenes put your own pinned apps around the icon, so you see how it sits next to the icons you actually have.

## 4. Export

> Make a Windows icon and a favicon set for my website.

| Format | You get |
| --- | --- |
| `ico` | A Windows icon with 16, 20, 24, 32, 40, 48, 64, 128 and 256 px images |
| `png` | One PNG, 256 px unless you pick a size |
| `icns` | A macOS icon, 16 to 1024 px including Retina sizes |
| `web` | A folder with `favicon.ico`, `apple-touch-icon.png`, 192 and 512 px app icons, a maskable icon for Android, `site.webmanifest`, and `head.html` with the tags to paste into your page |
| `pngset` | PNGs at 16, 24, 32, 48, 64, 128, 256, 512 and 1024 px |

Files go to `%LOCALAPPDATA%\iconwright\icons` on Windows and `~/.iconwright/icons` elsewhere, unless you name a folder (`make_icon`).

## Styles

A look is written as one short line, a **style string**. You'll see it in agent replies, in the studio's top bar and in the command line, and you can copy it between them.

```text
color=white bg=#2d5ba6 shape=squircle shadow
```

| Key | Values | Default |
| --- | --- | --- |
| `color` | Any CSS color: `white`, `#e9c46a`, `rgb(…)`, `hsl(…)`. Recolors the artwork. | The artwork's own colors |
| `bg` | A CSS color, or a gradient: `linear-gradient(135deg,#e9c46a,#c47335)` | None (transparent) |
| `shape` | `none`, `square`, `rounded`, `squircle`, `circle` | `rounded` when there's a background |
| `radius` | 0 to 0.5, a fraction of the icon size (for `rounded`) | 0.22 |
| `padding` | 0 to 0.45, the space around the artwork | 0.08, or 0.2 with a background |
| `shadow` | On when present | Off |

Recoloring replaces every color in the artwork with one color, which suits single-color icons. For multicolor logos, leave `color` out and add a background instead.

## Tips for icons that read well

- **Check 16 and 24 px.** Taskbars, title bars and browser tabs use tiny sizes. Thin lines and fine detail disappear; bold, simple shapes survive. The `sizes` scene shows exactly what's left.
- **Check light and dark.** A white icon with no background vanishes on a light taskbar. Either add a background or pick a color with contrast on both.
- **Give backgrounds room.** With a shape behind the artwork, 0.18 to 0.24 padding usually looks balanced.
- **Match your neighbors.** On a taskbar, icons with backgrounds look larger than bare glyphs. Pick one approach for a set of apps.
- **macOS and iOS expect a full tile.** Their icons fill a rounded square; a bare glyph looks lost in the Dock. Use `shape=squircle` with a background for those.


---

# The studio

iconwright studio is a visual editor for icons in your browser. Search for artwork, adjust colors and shapes with live previews, see the icon on a taskbar, desktop and phone, and download it. It uses the same engine as the agent tools, so what you see is exactly what you get.

There are two ways to use it:

| | Online studio | Local studio |
| --- | --- | --- |
| Open it | [iconwright studio](/studio/) | `node bin/iconwright.mjs studio`, or ask your agent to “open the studio” |
| Artwork | Iconify icons and pasted SVG | Also your own files and, on Windows, your installed apps' icons |
| Get the result | Downloads | Downloads, saving to a folder, and applying to apps on Windows |
| Install needed | No | Yes |

## Working in the studio

1. **Pick artwork** on the left: search, paste SVG code, or (local, Windows) pick one of your pinned apps to restyle its own icon.
2. **Shape the look** on the right: recolor the artwork, add a solid or gradient background, choose a shape, and adjust corner radius, padding and shadow.
3. **Check it in place** in the middle. Choose the scenes you care about, set the app name shown under the icon, and pick the display scaling to mimic (100%, 150% or 200%).
4. **Explore**: “Show 6 ideas” renders six color and shape variations of the same artwork. Click one to use it. “Keep this version” saves the current design to compare later.
5. **Download** a Windows `.ico`, a PNG, a macOS `.icns`, a website icon set, or PNGs at every size.

## The style line

The bar at the top always shows the current look as a [style string](design.md#styles), such as `color=white bg=#2d5ba6 shape=squircle`. You can type in it too: press Enter and the controls follow.

## Working with your agent

The studio and your agent speak the same language:

- **From the agent to you.** Ask your agent to open the studio. It opens with the agent's current design loaded (`open_studio`).
- **From you to the agent.** “Copy for your agent” copies a line like this, ready to paste into the chat:

  ```text
  Use iconwright with source "ph:rocket-launch-fill" and style "color=white bg=#2d5ba6 shape=squircle".
  ```

- **Share a design.** The address bar holds the design, so you can bookmark it or send the link.

## Privacy and safety

- The online studio sends your choices to iconwright's server to render them, and searches go to Iconify. Nothing is stored.
- The local studio only listens on `127.0.0.1` and needs a secret token that's part of the link iconwright prints, so other websites can't use it. It stops when you close the command (or, when an agent opened it, when the agent session ends).
- Applying icons to apps from the local studio is the same operation as the `app_apply_icon` tool, with the same [undo](safety.md#how-to-undo-everything).


---

# Taskbar and apps

On Windows, iconwright can change any app's icon, and pin, unpin and reorder taskbar apps. This page explains what each change does and what you'll see.

## Change app icons

> Give Spotify a white icon on a dark circle.

iconwright makes the icon and puts it on the app's Start menu shortcut and its pinned taskbar shortcut (`app_apply_icon`). The app's own files are never touched.

- **Open windows update right away.**
- **Pinned apps that aren't running** keep their old picture until Explorer restarts. iconwright tells your agent when that's the case, and the agent can restart Explorer once at the end of all your changes (`taskbar_refresh`).
- **Many apps at once** cost the same as one. Ask for all of them in one sentence.

### Restyle each app's own icon

> Make all my taskbar icons white.

Instead of one shared picture, iconwright takes each app's current icon and restyles it: recolored, on a background, in a shape. This is how you get a uniform taskbar while every app keeps its recognizable logo. Under the hood that's `source: "app"`.

Preview first if you're unsure:

> Show me what Spotify, Steam and Discord would look like in white, and in white on dark circles.

### Use an icon file you already have

> Use C:\Icons\notes.ico for Notepad.

Any `.ico` works, and so do icons inside `.exe` and `.dll` files.

## Pin, unpin and reorder

> Pin Notepad and Calculator, unpin Edge, and put Notepad first.

All of that happens in **one** step (`taskbar_pins`). Windows only reads the pinned-apps list when Explorer starts, so iconwright restarts Explorer once:

- The taskbar and desktop blink for a second or two.
- **Open File Explorer windows close.** Other apps keep running.
- Tray icons may take a moment to come back.

Before every change, iconwright backs up the pinned-apps list. If anything fails halfway, it puts everything back exactly as it was.

Not sure what the result will be? Ask for a dry run:

> What would my taskbar look like if I pinned Notepad at position 3?

### Undo a pin change

> Undo my last taskbar change.

That restores the pinned-apps list from just before the latest change (`taskbar_restore_backup`). To go all the way back to how it was before you ever used iconwright, ask for the **original** backup.

## Check what's pinned

> What's on my taskbar?

This lists your pinned apps in order with their icon files (`taskbar_status`). To find an app's exact name, or to see where its shortcuts are, ask for its details (`find_apps`).

## Things to know

- **App updates can undo custom icons.** Some apps rewrite their Start menu shortcut when they update. Apply the icon again.
- **Store apps** (like Apple Music) get their pinned icon changed, but a running window may still show the app's own icon in some places.
- **The first pin needs an existing pin.** iconwright copies part of the pin format from an app that's already pinned. If your taskbar has no pins at all, pin any app by hand first.
- **Taskbar styling tools** such as TranslucentTB can turn themselves off after Explorer restarts quickly twice in a row. iconwright notices, restarts them, and can space out restarts on request. See [Safety and risks](safety.md#explorer-restarts).

## Undo icons

> Put Spotify's original icon back.
>
> Undo every icon change.

(`restore_icons`.) iconwright recorded each original before changing it.


---

# Desktop

iconwright can change desktop icons, line them up, resize them, and save and restore their layout. Everything on this page applies immediately, without restarting Explorer.

## Change a desktop icon

> Give my "Projects" folder a blue folder icon.

Works for shortcuts (`.lnk`), web links (`.url`), folders, and the system icons: This PC, Recycle Bin, your user folder, Network and Control Panel (`desktop_apply_icon`).

Plain files, like a `.txt` or `.pdf`, can't have their own icon: Windows picks those by file type. Make a shortcut to the file and change the shortcut's icon instead.

## Arrange icons

> Save my desktop layout, then line up the icons by type from the top right.

- **Save first.** A saved layout (`desktop_layout`, action `save`) lets you put every icon back exactly where it was.
- **Arrange** sorts by name or type, fills columns or rows, and starts from any corner (`desktop_arrange`). You can name icons to put first.
- **Several monitors:** arranging works on one monitor at a time and leaves icons on the others where they are. Monitor 0 is the primary display.
- **Move one icon** to an exact spot with its coordinates (`desktop_move`). Positions snap to the desktop grid.

## Settings

> Make desktop icons small and hide the Recycle Bin.

| Setting | Options |
| --- | --- |
| Icon size | small (32 px), medium (48), large (96), xl (128), huge (256), or any size from 16 to 256 |
| Auto arrange | on or off |
| Align to grid | on or off |
| Show desktop icons | on or off (hides all of them, like right-click → View → Show desktop icons) |
| System icons | show or hide This PC, Recycle Bin, your user folder, Network, Control Panel |

(`desktop_settings`; several at once in one request.)

## See the result

> Show me the desktop.

iconwright takes a picture of the desktop icons, even if windows cover them (`capture`).

## Undo

| What | How |
| --- | --- |
| Positions, size, auto-arrange | Load the layout you saved: “restore my desktop layout” |
| A changed icon | “put the original icon back on Projects” (`restore_icons`) |
| Hidden system icons | Ask to show them again |


---

# MCP tools

<!-- Generated by site/build.mjs from src/tools.mjs. Don't edit by hand. -->

iconwright's MCP server has 20 tools. The design tools work on any OS; the rest need Windows and only appear there.

Every tool rejects arguments it doesn't know, so a typo is an error instead of being silently ignored. Read-only tools are marked so clients can run them without asking.

**Style strings.** Tools that style an icon take one `style` argument: space-separated `key=value` pairs. Keys: `color` (recolors the artwork), `bg` (a CSS color or `linear-gradient(135deg,#a,#b)`), `shape` (`none`, `square`, `rounded`, `squircle`, `circle`), `radius` (0–0.5), `padding` (0–0.45) and `shadow`. Example: `color=white bg=#2d5ba6 shape=squircle shadow`.

## Design

### `search_icons`

Search 200,000+ open-source icons (Iconify). Returns ids and, by default, a numbered contact sheet: picture N is icons[N-1]. Brand logos: "simple-icons:<brand>".

Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `query` (required) | string | What to look for, e.g. "music note" |
| `limit` | integer | Results (default 24) |
| `start` | integer | Skip this many results (next page) |
| `collections` | string[] | Only these icon sets, e.g. ["mdi", "ph", "lucide"] |
| `palette` | "mono" \| "color" | mono: single-color icons (recolor cleanly); color: multicolor |
| `preview` | boolean | Include the contact sheet (default true) |

### `design_icons`

Compare options in one small image: rows A, B, … = sources, columns 1, 2, … = styles; each cell shows the icon large and at 24 px on dark and light. Pass a picked cell's (e.g. "B2") source and style to preview_icon, make_icon or app_apply_icon. Max 36 cells. Nothing is saved.

Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `sources` (required) | string[] | Rows: icon ids, files, raw <svg> or "app:<name>" |
| `styles` | string[] | Columns: style strings (see make_icon), e.g. ["color=white", "color=white bg=#1DB954 shape=squircle"] |

### `preview_icon`

Mock up an icon where it lives: taskbar, start, desktop, explorer, browser, dock, ios, android, sizes (sizes = true pixels). On Windows, taskbar and start show the user's own pinned apps around it. Use before applying: catches icons that vanish on light or dark. Nothing is saved.

Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `source` (required) | string | Iconify id ("mdi:music"), image file, raw <svg>, or "app:<name>" (an installed app's icon; Windows) |
| `style` | string | Look, "key=value ...": color=<css> (recolors art), bg=<css or linear-gradient(135deg,#a,#b)>, shape=none\|square\|rounded\|squircle\|circle, radius=0-0.5, padding=0-0.45, shadow |
| `label` | string | App name shown under the icon |
| `scenes` | "taskbar" \| "start" \| "desktop" \| "explorer" \| "browser" \| "dock" \| "ios" \| "android" \| "sizes"[] | Default taskbar, start, desktop, sizes |
| `scale` | 1 \| 1.5 \| 2 | Display scaling to mimic (default 1) |

### `make_icon`

Write icon files: ico (Windows, 16-256 px), png, icns (macOS), web (favicons, touch + PWA icons, manifest, head.html), pngset (16-1024 px). Default ico + png. Returns paths and a preview (48 and 24 px on dark and light).

Writes files only.

| Argument | Type | Description |
| --- | --- | --- |
| `source` (required) | string | Iconify id ("mdi:music"), image file, raw <svg>, or "app:<name>" (an installed app's icon; Windows) |
| `style` | string | Look, "key=value ...": color=<css> (recolors art), bg=<css or linear-gradient(135deg,#a,#b)>, shape=none\|square\|rounded\|squircle\|circle, radius=0-0.5, padding=0-0.45, shadow |
| `name` | string | File name (default "icon") |
| `outDir` | string | Output folder (default: iconwright's icons folder) |
| `formats` | "ico" \| "png" \| "icns" \| "web" \| "pngset"[] | Default ["ico","png"] |
| `pngSize` | integer | Size of the png (default 256) |
| `preview` | boolean | Return the preview image (default true) |

### `open_studio`

Open iconwright studio (a visual icon editor) in the user's browser, preloaded with a source and style, to fine-tune by hand. Its "Copy for your agent" button gives the user the exact source and style to paste back.

Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `source` | string | Iconify id ("mdi:music"), image file, raw <svg>, or "app:<name>" (an installed app's icon; Windows) |
| `style` | string | Look, "key=value ...": color=<css> (recolors art), bg=<css or linear-gradient(135deg,#a,#b)>, shape=none\|square\|rounded\|squircle\|circle, radius=0-0.5, padding=0-0.45, shadow |
| `label` | string | App name shown in the scenes |
| `open` | boolean | Open the browser (default true); false just returns the link |

## Apps and taskbar

### `find_apps`

Find installed apps (Start menu). With query: matching names and AppIDs. With apps: details for each (AppID, Start menu and pinned shortcuts, Store app or not).

Read-only. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `query` | string | Part of the name; omit both to list the first 50 |
| `apps` | string[] | App names (as find_apps shows them) or AppIDs |

### `app_apply_icon`

Put an icon on apps (Start menu + pinned shortcuts; open windows update live). Give source (source "app" restyles each app's own icon, e.g. all white) or icon (existing .ico). pin:true also pins. If the result has a hint, taskbar_refresh once after all changes. Undo: restore_icons.

Changes the PC. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `apps` (required) | string[] | App names (as find_apps shows them) or AppIDs |
| `source` | string | "app" (each app's own icon), Iconify id, image file or raw <svg> |
| `icon` | string | Existing .ico/.exe/.dll to use as is |
| `iconIndex` | integer | Icon index inside icon (default 0) |
| `style` | string | Look, "key=value ...": color=<css> (recolors art), bg=<css or linear-gradient(135deg,#a,#b)>, shape=none\|square\|rounded\|squircle\|circle, radius=0-0.5, padding=0-0.45, shadow |
| `name` | string | File name (single app) |
| `outDir` | string | Output folder (default: iconwright's icons folder) |
| `pin` | boolean | Also pin the apps |
| `refresh` | boolean | Restart Explorer at the end if pinned icons need it |
| `noRestart` | boolean | Write the change but don't restart Explorer (shows after the next restart) |
| `restartCooldown` | integer | Wait until this many seconds since the last Explorer restart (helps taskbar styling tools) |

### `taskbar_status`

Pinned taskbar apps in order, with each one's icon file.

Read-only. Windows only.

No arguments.

### `taskbar_pins`

Change pinned apps in ONE Explorer restart: pin, unpin and move apps in a single call (the taskbar blinks; open File Explorer windows close). dryRun shows the resulting order without changing anything. Backed up first (undo: taskbar_restore_backup).

Changes the PC; restarts Explorer. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `pin` | string[] | Apps to pin |
| `unpin` | string[] | Apps to unpin |
| `order` | string[] | Pinned apps (incl. ones being pinned) to move to position, in this order |
| `position` | integer | Where order goes: 0 = first (default), -1 = last |
| `icon` | string | An .ico for the new pin (single app) |
| `dryRun` | boolean | Only report what would happen |
| `noRestart` | boolean | Write the change but don't restart Explorer (shows after the next restart) |
| `restartCooldown` | integer | Wait until this many seconds since the last Explorer restart (helps taskbar styling tools) |

### `taskbar_refresh`

Restart Explorer once so pinned icons reload. Only when a result says so; once, after all changes.

Changes the PC; restarts Explorer. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `restartCooldown` | integer | Wait until this many seconds since the last Explorer restart (helps taskbar styling tools) |

### `taskbar_restore_backup`

Put the pinned-apps list back: "last" = before the latest pin change, "original" = before iconwright's first. Restarts Explorer.

Changes the PC; restarts Explorer. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `from` | "last" \| "original" | Default "last" |

## Desktop

### `desktop_info`

Desktop icons with positions (px), icon size, options, grid spacing, monitors and system icon visibility.

Read-only. Windows only.

No arguments.

### `desktop_move`

Move desktop icons to positions (snap to the grid). Coordinates as in desktop_info.

Changes the PC. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `moves` (required) | { item: string, x: integer, y: integer }[] | Each: item (name or path from desktop_info), x and y in pixels |

### `desktop_arrange`

Line up the icons on one monitor from a corner; other monitors stay put. Save a layout first (desktop_layout).

Changes the PC. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `itemsFirst` | string[] | Items to place first, in order; the rest follow |
| `by` | "name" \| "type" \| "none" | Sort the rest (default name) |
| `corner` | "top-left" \| "top-right" \| "bottom-left" \| "bottom-right" |  |
| `flow` | "columns" \| "rows" | Fill columns (default) or rows first |
| `monitor` | integer | 0 = primary (default) |

### `desktop_settings`

Icon size, auto-arrange, snap to grid, show/hide all icons, and which system icons (This PC, Recycle Bin, …) show. Only the options you give change.

Changes the PC. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `iconSize` | "small" \| "medium" \| "large" \| "xl" \| "huge" \| integer | small 32, medium 48, large 96, xl 128, huge 256, or px |
| `autoArrange` | boolean |  |
| `snapToGrid` | boolean |  |
| `showIcons` | boolean | false hides every desktop icon |
| `showSystemIcons` | "this-pc" \| "recycle-bin" \| "user-files" \| "network" \| "control-panel"[] |  |
| `hideSystemIcons` | "this-pc" \| "recycle-bin" \| "user-files" \| "network" \| "control-panel"[] |  |

### `desktop_apply_icon`

Change the icon of a desktop shortcut, web link, folder or system icon (this-pc, recycle-bin, …). Give source (makes an icon) or icon (existing .ico). Plain files can't have their own icon. Undo: restore_icons.

Changes the PC. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `item` (required) | string | Name or path from desktop_info, or a system icon name |
| `source` | string | Iconify id ("mdi:music"), image file, raw <svg>, or "app:<name>" (an installed app's icon; Windows) |
| `icon` | string | Existing .ico/.exe/.dll |
| `iconIndex` | integer |  |
| `style` | string | Look, "key=value ...": color=<css> (recolors art), bg=<css or linear-gradient(135deg,#a,#b)>, shape=none\|square\|rounded\|squircle\|circle, radius=0-0.5, padding=0-0.45, shadow |
| `name` | string |  |
| `outDir` | string | Output folder (default: iconwright's icons folder) |

### `desktop_layout`

save: icon positions, size and auto-arrange to a JSON file. load: put icons back where it had them (reports items that are gone).

Changes the PC. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `action` (required) | "save" \| "load" |  |
| `file` | string | Default: iconwright's desktop-layout.json |

## Undo and checks

### `restore_icons`

Put original icons back: on apps, on desktop items, or all:true for everything iconwright changed (pins excepted; see taskbar_restore_backup). If needsRefresh, call taskbar_refresh once.

Changes the PC. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `apps` | string[] | App names (as find_apps shows them) or AppIDs |
| `desktopItems` | string[] | Desktop items or system icon names |
| `all` | boolean |  |

### `doctor`

Read-only check that the taskbar and desktop tools can work here (Windows, PowerShell, pin list, backups, taskbar mods).

Read-only. Windows only.

No arguments.

### `capture`

See a change: the taskbar (default), the desktop icons (drawn even under windows; no wallpaper), or the screen. Fails while the screen is locked.

Read-only. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `what` | "taskbar" \| "desktop" \| "screen" |  |
| `maxWidth` | integer | Scale down to this width (default 1600; 0 = full) |

## Prompts

Clients that support MCP prompts show these as commands; in Claude Code they're in the `/` menu, marked (MCP).

- **restyle-taskbar**: Make every pinned taskbar icon match one look (e.g. all white).
- **design-icon**: Design an icon from an idea, compare options, preview it in context, then export or apply it.
- **tidy-desktop**: Back up the desktop layout, then arrange icons neatly.
- **undo-everything**: Put back every icon iconwright changed and, if wanted, the original pinned apps.


---

# Command line

Everything the agent tools do is also available as a command. Run commands from the iconwright folder:

```bash
node bin/iconwright.mjs <command> [options]
```

`node bin/iconwright.mjs help` lists the commands, and `<command> --help` shows one command's options. Unknown options are errors, so a typo never runs silently.

**Sources** are an Iconify id (`mdi:music`), an image file (`.svg`, `.png`, `.jpg`, `.webp`, `.ico`), raw `<svg>` text, or (on Windows) `app:<App name>` for an installed app's current icon.

**Styles** are given as one string, `--style "color=white bg=#2d5ba6 shape=squircle shadow"`, or as separate flags: `--color`, `--bg`, `--shape`, `--radius`, `--padding`, `--shadow`. Separate flags win over the same key in `--style`. See [style strings](design.md#styles).

## Design (any OS)

| Command | What it does |
| --- | --- |
| `search <query>` | Prints matching Iconify ids. `--limit N`, `--start N` (next page), `--collections mdi,ph`, `--palette mono\|color`, `--sheet out.png` (also saves a numbered contact sheet). |
| `design <source...> --out grid.png` | Renders a comparison grid: sources in rows, styles in columns. `--styles "style one\|style two"`. Prints the legend. |
| `preview <source> --out scenes.png` | Mocks the icon up on real surfaces. `--style`, `--label "App name"`, `--scenes taskbar,start,desktop,explorer,browser,dock,ios,android,sizes`, `--scale 1\|1.5\|2`. |
| `make <source>` | Writes icon files. `--formats ico,png,icns,web,pngset` (default `ico,png`), `--name`, `--out folder`, `--png-size N`, plus style options. |
| `studio [source]` | Opens the [studio](studio.md) in your browser. `--style`, `--port N`, `--no-open`. Runs until you press Ctrl+C. |
| `sheet <images...> --out sheet.png` | Puts image files (PNG or ICO) side by side with their names. |

Examples:

```bash
node bin/iconwright.mjs search rocket --palette mono --sheet rockets.png
node bin/iconwright.mjs design ph:rocket-launch-fill tabler:rocket --styles "color=white bg=#2d5ba6 shape=squircle|color=#e9c46a bg=#1f2228 shape=circle" --out grid.png
node bin/iconwright.mjs preview ph:rocket-launch-fill --style "color=white bg=#2d5ba6 shape=squircle" --label Launcher --out scenes.png
node bin/iconwright.mjs make ph:rocket-launch-fill --style "color=white bg=#2d5ba6 shape=squircle" --formats ico,icns,web --name launcher
```

## Apps and taskbar (Windows)

| Command | What it does |
| --- | --- |
| `apps [text]` | Finds installed apps by name. Prints exact names and AppIDs. |
| `info <app...>` | Shows an app's AppID, Start menu shortcuts, pinned shortcuts and whether it's a Store app. |
| `apply <app...> --source <ref>` | Makes an icon and puts it on the apps. `--source app` restyles each app's own icon. `--pin` also pins them; `--refresh` restarts Explorer at the end if needed. Or `apply <app> --icon file.ico` to use an existing icon. |
| `status` | Lists pinned apps in order with their icon files. |
| `pins` | Pins, unpins and reorders in one Explorer restart: `--pin a,b`, `--unpin c`, `--order a,b`, `--position N` (0 = first, -1 = last), `--dry-run`, `--no-restart`, `--restart-cooldown N`. |
| `refresh` | Restarts Explorer so pinned icons reload. |
| `restore <app...>` | Puts the original icons back. `restore --all` restores every app and desktop icon iconwright changed. |
| `restore-pins` | Puts the pinned-apps list back. `--from last` (default) or `--from original`. |

`pin`, `unpin` and `reorder` still work as shortcuts for `pins`.

```bash
node bin/iconwright.mjs apply Spotify Steam Discord --source app --style "color=white"
node bin/iconwright.mjs pins --pin Notepad --order Notepad --position 0 --dry-run
node bin/iconwright.mjs restore --all
```

## Desktop (Windows)

| Command | What it does |
| --- | --- |
| `desktop list` | Icons with positions, icon size, options, grid spacing and monitors. |
| `desktop move <item> --x px --y px` | Moves one icon (snaps to the grid). |
| `desktop arrange [items first...]` | Lines icons up. `--by name\|type\|none`, `--corner top-left\|top-right\|bottom-left\|bottom-right`, `--flow columns\|rows`, `--monitor N`. |
| `desktop size <size>` | `small`, `medium`, `large`, `xl`, `huge`, or pixels from 16 to 256. |
| `desktop options` | `--auto-arrange on\|off`, `--snap on\|off`, `--icons on\|off`. |
| `desktop system <names...> --show\|--hide` | `this-pc`, `recycle-bin`, `user-files`, `network`, `control-panel`. |
| `desktop apply <item>` | Changes a desktop item's icon: `--source <ref>` plus style options, or `--icon file.ico`. |
| `desktop restore <item...>` | Puts original icons back. |
| `desktop save <file.json>` / `desktop load <file.json>` | Saves or restores icon positions, size and auto-arrange. |

## Checks (Windows)

| Command | What it does |
| --- | --- |
| `doctor` | Checks that the taskbar and desktop tools can work on this PC. Changes nothing. |
| `capture [taskbar\|desktop\|screen]` | Saves a screenshot. `--out file.png`, `--max-width px`. Doesn't work while the screen is locked. |

## Testing (any OS)

| Command | What it does |
| --- | --- |
| `report` | Prints your system details and a quick self-test as Markdown, for [test reports](contributing.md). Names no apps, files or user folders. `--out report.md` saves it. |
| `mcp` | Starts the MCP server on stdio (the same as `bin/iconwright-mcp.mjs`). |

## Output and exit codes

Commands print plain text or compact JSON. Windows paths use forward slashes, and every command accepts them back. On failure, a command prints a one-line error and exits with code 1.


---

# Safety and risks

iconwright changes real settings on your PC. This page lists exactly what it touches, how to undo each change, and what could go wrong.

**Short version:** designing and exporting icons changes nothing on your PC except the files you ask for. Icon changes are small and fully undoable. Pinning, unpinning and reordering are the riskiest part: they edit an undocumented Windows setting and restart Explorer, so iconwright backs up the pinned-apps list before every change and rolls back if anything fails.

## What iconwright changes

| Feature | What it changes | Undo (agent tool) |
|---|---|---|
| Design, preview, export | Nothing on the PC; files only where you ask (`make_icon`) | Delete the files |
| App icon (`app_apply_icon`) | The icon setting inside the app's Start menu shortcut and pinned shortcut (`.lnk` files). The app itself isn't modified. | `restore_icons` |
| Pin, unpin, reorder (`taskbar_pins`) | The pinned-apps list in the registry (`HKCU\…\Explorer\Taskband`) and the shortcut files in your pinned-apps folder. **Restarts Explorer.** | `taskbar_restore_backup` |
| Desktop shortcut or link icon | The icon setting inside that `.lnk` or `.url` file | `restore_icons` |
| Desktop folder icon | A hidden `desktop.ini` file inside the folder; the folder is marked read-only (the standard Windows way to show a custom folder icon) | `restore_icons` |
| This PC, Recycle Bin and other system icons | A per-user registry override (`HKCU\…\Explorer\CLSID\{id}\DefaultIcon`) | `restore_icons` |
| Show or hide system desktop icons | The same setting as *Settings → Personalization → Themes → Desktop icon settings* | `desktop_settings` |
| Desktop icon positions, size, auto-arrange | Explorer's saved desktop layout | `desktop_layout` load (save a layout first) |

iconwright only changes settings for **your Windows user**. It never needs administrator rights. Shortcuts shared by all users (in `C:\ProgramData`) are skipped and reported as `skipped`.

Nothing is sent anywhere. The only network requests are icon searches and downloads from [Iconify](https://iconify.design). The online [studio](studio.md) is the one exception you choose to use: it renders designs on iconwright's server and stores nothing.

### Files iconwright keeps

All in `%LOCALAPPDATA%\iconwright\`:

| Path | What |
|---|---|
| `icons\` | The icons it made. **Your shortcuts point at these files**: deleting them makes the icons go blank. |
| `state.json` | The original icon of everything iconwright changed, for undo. |
| `backups\original\` | The pinned-apps list from before iconwright first changed it. Kept forever. |
| `backups\last\` | The pinned-apps list from before the most recent pin change. |
| `cache\` | Downloaded Iconify artwork and extracted app icons, to make repeat designs fast. Safe to delete. |
| `desktop-layout.json` | Your saved desktop layout, if you saved one without naming a file. |
| `bin\` | A small compiled helper (built on first use from `scripts/win/Iconwright.Win.cs`). |
| `captures\` | Screenshots from `capture`. |

## Explorer restarts

Windows only reads the pinned-apps list when Explorer starts, so **pin changes, refresh and restoring a pin backup restart Explorer**. When that happens:

- The taskbar and desktop disappear for one to three seconds and come back.
- **Open File Explorer windows close.** Other apps keep running.
- Tray icons of some apps may take a moment to reappear.

iconwright keeps this as gentle as it can:

- It batches: pinning three apps, unpinning one and moving another is one call and one restart.
- It can do a dry run that shows the resulting order without changing anything.
- It saves the desktop layout first, so icon positions aren't lost.
- It stops only the Explorer process that owns the taskbar, waits until a new taskbar is really there before reporting success, and starts Explorer itself if Windows doesn't.
- Only one change runs at a time, even if an agent sends several at once.

### Taskbar styling tools

Tools like **TranslucentTB** switch themselves off if Explorer restarts twice within about 30 seconds (a safety feature). iconwright:

- checks the taskbar color before and after each restart and tells you if the styling was lost,
- restarts TranslucentTB, TaskbarX or RoundedTB if they stopped,
- can wait between restarts on request (`restartCooldown`, in seconds) when you make many changes in a row.

**StartAllBack** works fine; it's what iconwright was developed on.

## How to undo everything

Ask your agent: “Undo everything iconwright changed, including my pinned apps.” Or run:

```bash
node bin/iconwright.mjs restore --all                 # every app and desktop icon back to the original
node bin/iconwright.mjs restore-pins --from original  # pinned apps as they were before iconwright
node bin/iconwright.mjs refresh                       # make sure pinned icons reload
```

Then you can delete `%LOCALAPPDATA%\iconwright\` and uninstall the plugin (`/plugin uninstall iconwright` in Claude Code).

### If the taskbar looks wrong and iconwright can't fix it

The pinned-apps backups are ordinary Windows files, so you can restore them by hand:

1. Open `%LOCALAPPDATA%\iconwright\backups\last\` (or `original\`).
2. Copy the shortcuts from its `TaskBar` folder into `%APPDATA%\Microsoft\Internet Explorer\Quick Launch\User Pinned\TaskBar`.
3. Double-click `taskband.reg` and confirm.
4. Restart Explorer: open Task Manager, find **Windows Explorer**, right-click it and choose **Restart**.

If the taskbar disappears and doesn't come back: press **Ctrl+Shift+Esc** to open Task Manager, choose **Run new task**, type `explorer.exe` and press Enter.

## Known risks

From most to least likely to matter:

1. **Windows updates could break pinning.** The pinned-apps list uses a binary format Microsoft doesn't document. iconwright refuses to edit it if the layout looks unfamiliar (it fails safely with an error), but a future Windows version could change how it's read. Icon changes and desktop features use documented interfaces and are much less exposed.
2. **Explorer restarts are disruptive.** See above. Make pin changes when you're not in the middle of something in File Explorer.
3. **Limited testing.** iconwright has been tested on one Windows 11 PC (see [Compatibility](compatibility.md)). The stock Windows 11 taskbar, Windows 10, multiple monitors and non-English Windows haven't been tested yet.
4. **App updates can undo custom icons.** Some apps recreate their Start menu shortcut when they update. Apply the icon again afterwards.
5. **The first pin needs an existing pin.** iconwright copies part of the pin format from an app that's already pinned. If nothing is pinned, it stops with a clear error; pin any app by hand first.
6. **Security software might object.** iconwright compiles a small helper with PowerShell's `Add-Type` and edits the registry. Some antivirus tools flag that pattern. It hasn't happened in testing.
7. **Store apps** (like Apple Music): the pinned icon changes, but the icon of the running window may stay the app's own.
8. **The local studio is a web server.** It listens only on `127.0.0.1` and requires a per-session secret token, so websites can't reach it. Close it when you're done.

## When the screen is locked

Some things need a visible, unlocked desktop. While the screen is locked or the sign-in screen is showing:

- **Screenshots (`capture`) fail** with a message saying the screen is locked. Unlock and ask again.
- **The taskbar-style check is skipped.** After an Explorer restart, iconwright compares the taskbar's color before and after to notice when a styling tool like TranslucentTB lost its look. It can't read the taskbar while the screen is locked, so it reports no colors and can't warn you.
- **You can't see the result.** Icon and pin changes still apply, but check them on screen after you unlock before relying on them.

If you're asking an agent to work while you're away, tell it to skip screenshots and pin changes, or leave the screen unlocked.

## Things iconwright can't do

- Give a single ordinary file (like a `.txt`) its own icon. Windows picks those by file type. Use a shortcut to the file instead.
- Change the color of desktop icon labels (Windows always draws them white with a shadow).
- Change icons of apps for other Windows users.


---

# Compatibility

iconwright 0.2 is an early release. This page says what has been tested, on what, and how.

## Operating systems

| | Design and export | Taskbar and app icons | Desktop |
|---|---|---|---|
| **Windows 11** | Yes | Yes (tested) | Yes (tested) |
| **Windows 10** | Yes | Should work, not tested | Should work, not tested |
| **macOS** | Yes (tested in CI) | No | No |
| **Linux** | Yes (tested in CI) | No | No |
| **Any browser** | Yes, in the online [studio](studio.md) | No | No |

On macOS and Linux, iconwright offers the design tools: search, design grids, scene previews, export, and the local studio. The Windows commands say they're Windows-only instead of failing in confusing ways. The MCP server doesn't list the Windows tools there at all.

**Why not Linux or macOS?** The taskbar and desktop features are built on Windows-only parts of the system: shortcut files, Explorer, the Windows registry. Linux desktops (GNOME, KDE) and macOS use completely different mechanisms (`.desktop` files and icon themes, or app bundles and the Dock). Supporting them would mean writing a separate version of the apply layer for each. It's possible, but not planned for now.

## What has been tested

All on one PC: **Windows 11 build 26200**, 200% display scaling, one monitor, English, with **StartAllBack 3.9** (a taskbar replacement) and **TranslucentTB**. Node 24.

| Feature | How it was checked |
|---|---|
| Change a running app's icon (T3 Code, an Electron app) | Seen on screen, via the CLI and via MCP |
| Change a Store app's pinned icon (Apple Music) | Seen on screen |
| Pin a classic app (Character Map) and an Electron app | Seen on screen; the pinned button merges with the running window |
| Pin two apps in one restart; unpin | Seen on screen |
| Pin, then move the new pin to position 2, in one restart; then unpin (`pins`) | Pin order read back: identical to before |
| Dry run of mixed pin, unpin and order requests, including duplicates and conflicts | Results checked against the live pin list; nothing changed |
| Reorder pinned apps | Order read back after the restart, and seen on screen |
| Undo pin changes from backups (`restore-pins`) | Pin order read back before and after |
| Roll back a failed pin-list write | Forced failure; the registry bytes came back identical |
| Desktop: move, arrange, size, auto-arrange, hide icons, show and hide system icons, re-icon a shortcut, restore, save and load a layout | Seen on screen (desktop screenshots) |
| `restore --all` | Icon read back after restoring |
| Restyle two pinned apps at once from their own icons, then restore (MCP) | Icon settings read back: changed, then exactly the originals |
| Restyle Steam with a Steam game pinned next to it | Seen on screen: only Steam changes (the game's pin launches steam.exe with arguments) |
| Install from the npm package tarball; start the MCP server with npx | 20 tools listed and a live call answered |
| Extract an app's own icon (custom `.ico`, `.exe` resources, Steam) | Images checked by eye: 256 px with transparency |
| Desktop `.url` with non-ASCII text, and a folder without `desktop.ini`: set and restore | Files compared byte for byte after restore |
| Pin and unpin through MCP with the trimmed environment MCP clients use | Pin count read back |
| A failed pin-list change | Forced failure: registry bytes and pinned shortcut files came back; the `last` backup was untouched |
| TranslucentTB failsafe detection | Seen on screen |
| Fresh install as a Claude Code plugin (local marketplace) | Installed into a clean Claude config; MCP server connected; an agent used `doctor`, `taskbar_status` and `capture` |
| Codex through MCP | Registered with `codex mcp add`; an agent used `doctor`, `taskbar_status` and `capture` |
| Design grid with `app:` sources, scene previews with the user's own pinned apps, web and `.icns` export (MCP) | Images checked by eye; `.ico`, `.icns` and zip files checked by parsing them |
| Local studio (search, ideas, kept versions, app icons, downloads) and hosted studio API | Used in a browser; hosted mode refuses file paths and unsafe SVG |
| Icon making on Linux and macOS | GitHub Actions on Ubuntu and macOS |

## Not tested yet

- The **stock Windows 11 taskbar** (without StartAllBack). The pin format is Windows' own, so it's expected to work, but it hasn't been checked.
- **Windows 10**, **multiple monitors** (arranging per monitor is implemented but untested), **non-English Windows**, **100% and 150% scaling**.
- **Explorer Patcher**, **Windhawk** taskbar mods, **Start11**.
- **Pinning when no app is pinned yet.** iconwright stops with a clear error by design.
- Running as **administrator**, and shortcuts shared by all users.
- The running-window icon of **Store apps**.
- Installing the Claude Code plugin **from GitHub** (only a local copy was tested).

If you try iconwright on one of these, please [open an issue](https://github.com/JayceeGupta/iconwright/issues) with the output of `node bin/iconwright.mjs doctor`, whether it worked or not.

## Readiness

| Area | Status | Why |
|---|---|---|
| Making icons | **Beta** | Automated tests on three OSes; many source formats. |
| Design grids, scenes, studio | **Beta** | New in 0.2; tested on Windows and in CI. Scene geometry follows published platform sizes, not pixel captures. |
| App icons | **Beta** | Uses documented shortcut settings; confirmed on screen for several app types. |
| Desktop | **Beta** | Uses documented Windows interfaces; confirmed on screen. Tested on one PC. |
| Pin, unpin, reorder | **Experimental** | Works and is backed up, but depends on an undocumented format that Windows updates could change. |
| MCP, CLI, plugin | **Beta** | Tested end to end with Claude Code and Codex on one PC. |

## Requirements

- Node.js 20 or newer.
- Windows PowerShell 5.1 (included with Windows 10 and 11). PowerShell 7 isn't needed.
- No administrator rights.
- Internet access only for Iconify icon names and the one-time install of the image library.


---

# How it works

This page explains how iconwright does each thing, in plain terms. For byte-level details, see [Windows internals](windows-internals.md).

## The big picture

```text
 Claude Code ─┐
 Codex ───────┼──>  MCP server ─┐
 other agents ┘                 │
 you ─────────────>  CLI ───────┼──> icon engine (Node + sharp)        any OS
 you ─────────────>  studio ────┘     search, grids, scenes, export
                                │
                                └──> Windows layer (PowerShell + C#)   Windows only
                                        │
                                        ├─ shortcut files (.lnk, .url, desktop.ini)
                                        ├─ registry (pinned apps, system icons)
                                        └─ Explorer (desktop icon view, taskbar)
```

- The **MCP server**, the **CLI** and the **studio** are three front doors to the same code. Agents use MCP; people use the CLI or the studio. The MCP tools are defined once, as data, in `src/tools.mjs`; the docs' [tool reference](tools.md) is generated from the same table.
- The **icon engine** is plain Node.js, so it runs anywhere, including the hosted studio's server.
- The **Windows layer** is a PowerShell script plus a small C# helper. The helper is compiled once on first use and cached in `%LOCALAPPDATA%\iconwright\bin`. It does the low-level work: shortcut files, the pinned-apps list, the desktop view, icon extraction and screenshots.

### Speed: one PowerShell for the whole session

Starting PowerShell takes about a second. The CLI starts one per command, which is fine for people. The MCP server instead keeps **one PowerShell process running** and sends it requests as lines of JSON. Most calls then take 50 to 600 ms instead of 2 to 3 seconds. After any command that restarts Explorer, that process is retired and a fresh one starts on the next call, so nothing in it refers to the old Explorer. Requests run one at a time; a request that takes over 5 minutes stops the process and reports that the change may be incomplete.

### Strict inputs

Every MCP tool rejects arguments it doesn't know, and the CLI rejects unknown options. A typo like `colour` fails with an error instead of being silently ignored. Each tool also tells the client whether it only reads, changes something, or restarts Explorer.

## Making an icon

1. **Get the artwork.** An Iconify id like `simple-icons:spotify` is fetched from the [Iconify API](https://iconify.design); many ids are fetched together, one request per icon set, and kept in a disk cache. Files (SVG, PNG, JPEG, WebP, ICO) are read from disk; for an `.ico`, the largest image inside it is used. On Windows, `app:<name>` extracts an installed app's current icon at 256 px.
2. **Recolor** (optional). For SVGs, iconwright rewrites the fill and stroke colors, leaving masks and clip paths alone. For raster images, it paints every visible pixel the new color and keeps the transparency, so multicolored pictures become single-colored.
3. **Fit it.** Transparent edges are trimmed, then the artwork is centered on a 1024×1024 canvas with some padding. This recolored, trimmed artwork is cached in memory, so trying ten styles on one icon only does this work once.
4. **Background** (optional). A square, rounded square, squircle or circle, in a color or a CSS-style gradient, goes behind it, with an optional soft shadow under the artwork.
5. **Export.** The `.ico` holds nine sizes (16, 20, 24, 32, 40, 48, 64, 128 and 256 px), so Windows has a sharp image at every display scaling. The `.icns`, favicon set and PNG set are made from the same 1024 px master. A small **preview** (the icon at 48 and 24 px on dark and light) comes back with every result.

### Grids and scenes

Design grids, search sheets and scene mockups are drawn with the same engine. Text in them uses a bundled copy of the Inter font, so the images look the same on Windows, macOS, Linux and the hosted studio's server. Scene geometry follows each platform's published sizes: 24 px taskbar icons in a 48 px bar, 32 px Start icons, 48 px desktop icons, and the iOS and Android masks.

When an agent applies a new look, the icon file name gets a short code based on the style (for example `spotify-3fa9c1.ico`). Windows caches icons by file path, so a new name is the reliable way to make it show the new look.

## Changing an app's icon

Windows apps are found through the Start Menu: `apps` and `info` look up the app's name, its shortcut and its **AppUserModelID** (the ID Windows uses to group an app's windows on the taskbar).

`apply` then:

1. saves the current icon setting of each shortcut (in `state.json`, for `restore`),
2. points the app's **Start Menu shortcut** and its **pinned shortcut** at the new `.ico`,
3. tells Explorer the shortcuts changed.

Where the change shows up depends on the app:

- **Running apps with an AppUserModelID** (most modern apps, including Electron apps like VS Code): the taskbar button takes its icon from the Start Menu shortcut, so it **changes immediately**.
- **Pinned apps that aren't running, and older apps without an ID**: Explorer reads the pinned shortcut only when it starts. iconwright tells the agent with a `hint`, and one `refresh` (an Explorer restart) applies it. If several apps need it, the agent makes all the changes first and refreshes once.
- **Store apps**: the pinned icon changes. The running window may keep the app's own icon, because Store apps declare it in their package.

### Restyling an app's own icon

With `source: "app"`, iconwright starts from the icon the app had before iconwright changed it, or its current one if it hasn't, looking at the pinned shortcut first since that's what the taskbar shows. If that's an `.ico` file, it's used directly. If it's inside an `.exe` or `.dll`, the 256 px version is extracted with its transparency. For Store apps, Windows' shell provides the image. The result is recolored like any other source. Several apps are handled in one request, and the agent gets one image comparing them all.

## Pinning, unpinning and reordering

There's no official way for a program to pin apps to the Windows 11 taskbar. Windows has a pinning interface, but it ignores calls from outside Explorer itself, and the "Pin to taskbar" menu item can't be triggered by other programs.

What does work is editing the list Explorer saves its pins in. All pin changes in one request (pin some apps, unpin others, move some) are planned together and written in one go, so they cost one Explorer restart. It lives in the registry (`HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\Taskband`) as two binary values: one with the location of each pinned shortcut, one with a copy of each shortcut. Explorer only reads them at startup, so iconwright:

1. backs up the list (and the pinned shortcuts),
2. stops Explorer,
3. edits the list: adds, removes or reorders entries, keeping both values in step,
4. lets Explorer start again (Windows restarts it automatically) and waits until the taskbar is back,
5. checks the result.

New pins need three small tags Explorer adds when you pin by hand ("pinned by the user", the time, and the app's ID). Without them Explorer keeps the entry but never shows it. Finding that took a lot of experimenting; it's documented in [Windows internals](windows-internals.md).

### What keeps it safe

- **Backups.** `backups\original` is saved before iconwright's first change and kept forever. `backups\last` is replaced only after a change succeeds. `restore-pins` puts either one back. Backups are taken before any file is touched.
- **Strict reading.** If the list contains anything iconwright doesn't fully understand, it refuses to change it rather than risk dropping pins.
- **Rollback.** If anything fails, the original registry bytes and pinned shortcut files are put back before Explorer restarts.
- **Only the taskbar process restarts.** iconwright stops the one `explorer.exe` that owns the taskbar. If you've set File Explorer to open folders in a separate process, those windows stay open.
- **It checks the taskbar came back.** If it doesn't within 30 seconds, iconwright says so and explains how to start it, instead of reporting success.
- **One at a time.** A system-wide lock means two requests can never overlap, even if an agent sends them in parallel. Reads wait too, so they never see a half-restarted taskbar.
- **Works in a trimmed environment.** Some MCP clients start servers with very few environment variables. Without one of them (`PATHEXT`), Windows PowerShell silently refuses to run programs like `reg.exe`. iconwright fills these in, and `doctor` checks for it.
- **Styling check.** The taskbar color is sampled before and after the restart, to notice when a styling tool like TranslucentTB switched itself off. iconwright restarts it if so.

## The desktop

Explorer draws desktop icons in a normal folder view, and Windows offers a documented interface to control it (`IFolderView2`). iconwright uses it to:

- list icons and their positions, and move them,
- arrange them from any corner, sorted by name or type,
- change the icon size, auto-arrange, align-to-grid and "show desktop icons".

These changes are **live**: no restart. Positions snap to Windows' icon grid. iconwright asks Explorer to save the layout after every change, because Explorer normally only saves it when it shuts down cleanly.

Desktop **icons** are changed the standard way for each kind of item:

| Item | Where the icon is set |
|---|---|
| Shortcut (`.lnk`) | The shortcut's icon setting |
| Internet shortcut (`.url`) | Its `IconFile` line |
| Folder | A hidden `desktop.ini` inside the folder |
| This PC, Recycle Bin, Network, … | A per-user registry override (Recycle Bin gets both its empty and full icon) |

Showing and hiding the system icons uses the same setting as Windows' *Desktop icon settings* dialog.

## Screenshots

`capture taskbar` copies the taskbar area of the screen. `capture desktop` asks the desktop icon view to draw itself into an image, so it works even when windows cover the desktop (the wallpaper isn't included). Images are scaled down to at most 1600 px wide to keep them cheap for agents to read.

## Checks

`doctor` reads, without changing anything: the Windows and PowerShell versions, whether the helper loads, whether apps can be looked up, whether the pinned-apps list is in a format iconwright understands, whether there's a pin to copy from, whether the taskbar and desktop are reachable, which taskbar mods are running, and whether backups exist.

## Code map

| Path | What it does |
|---|---|
| `bin/iconwright.mjs`, `bin/iconwright-mcp.mjs` | Entry points. On first run they install dependencies. |
| `src/tools.mjs` | Every MCP tool and prompt, as data, plus the server instructions |
| `src/mcp.mjs` | MCP server: registers the tools, serves a compact tool list, runs changes one at a time |
| `src/cli.mjs`, `src/cli-win.mjs` | CLI commands |
| `src/render.mjs`, `src/color.mjs` | Icon engine: styles, style strings, colors and gradients, `.ico` export |
| `src/source.mjs`, `src/ico.mjs` | Artwork: Iconify search and fetch with a disk cache, files, `.ico` decoding |
| `src/design.mjs`, `src/scenes.mjs`, `src/draw.mjs` | Search sheets, design grids, scene mockups, and the drawing kit they share |
| `src/formats.mjs`, `src/zip.mjs` | `.icns`, favicon sets, PNG sets; zips for studio downloads |
| `src/studio.mjs`, `studio/`, `api/studio.mjs` | The studio: its HTTP API (local and hosted), its web page, and the hosted function |
| `src/sheet.mjs` | Side-by-side sheets of image files |
| `src/apply.mjs` | "Make an icon and apply it" for apps and desktop items |
| `src/report.mjs` | `iconwright report`: system details and a self-test for test reports |
| `bin/ensure-deps.mjs` | Installs dependencies on a fresh clone's first run; a no-op when installed from npm |
| `src/win.mjs` | Runs the Windows layer: one process per call (CLI) or a long-lived worker (MCP) |
| `src/args.mjs` | Strict CLI option parsing |
| `src/output.mjs` | Tidies results for agents (forward-slash paths, no empty fields) |
| `scripts/win/iconwright.ps1` | Windows layer: apps, icons, pins, backups, Explorer restarts, checks |
| `scripts/win/desktop.ps1` | Windows layer: desktop |
| `scripts/win/Iconwright.Win.cs` | C# helper: shortcuts, pinned-apps list, desktop view, screenshots |
| `skills/iconwright/SKILL.md` | Instructions Claude Code loads to use iconwright well |


---

# Windows internals (verified 2026-10-27, Win11 26200 + StartAllBack 3.9)

Findings behind `scripts/win/`, for contributors. Read this before changing the pin, icon or
desktop logic. For a plain-language overview, see [How it works](how-it-works.md).

## Where a taskbar button's icon comes from
- **Running app with an explicit AppUserModelID** (Electron apps like T3 Code, VS Code): the icon
  of the Start Menu shortcut carrying that ID. Changing that shortcut's icon + `SHChangeNotify(UPDATEITEM)`
  updates the button **live**. Changing the pinned .lnk alone does nothing while the app runs.
  `WM_SETICON` on the window does nothing either.
- **Pinned, not running / apps without an explicit ID**: the pinned .lnk's icon, read when Explorer
  starts. Needs an Explorer restart (`refresh`) to show.
- Windows caches icons by file path → write each new look to a new file name (`apply` adds a style hash).

## Pinning
- `IPinnedList3::Modify` / `LegacyModify` (CLSID_TaskbandPin `90AA3A4E-…`, IID `0DD79AE2-…`) return S_OK
  but are **silently ignored outside explorer.exe**. Read methods (`IsPinned`, `GetChangeCount`) work.
- The "Pin to taskbar" verb only appears inside Explorer. Invoking it through Explorer's own
  `Shell.Application` (desktop view or a folder window) fails: `DoIt` → E_INVALIDARG, `InvokeVerb` → no-op.
- **What works**: write `HKCU\…\Explorer\Taskband` while Explorer is stopped, then start it.
  - `Favorites` = `{0x00, u32 cb, PIDL}* 0xFF`; `FavoritesResolve` = `{u32 cb, .lnk bytes}*`, same order.
  - PIDL = `UserPinned` known-folder item + `TaskBar` item (copied from an existing entry) + the file item.
  - The file item **must** carry three extra blocks, or Explorer keeps the entry but never shows it:
    `BEEF001E` `02 00`+"UserPinned\0" (UTF-16), `BEEF002B` FILETIME, `BEEF001D` `02 00`+AppID\0.
    Each block: `cb u16, ver u16=0, sig u32, payload, u16 offset-of-first-block`.
  - AppID = explicit ID if the shortcut has one, else the `Get-StartApps` AppID (e.g. `{1AC14E77-…}\charmap.exe`).
- Windows auto-restarts the shell after `Stop-Process explorer`. Writing right after the kill wins the race.

## Side effects
- Restarting Explorer twice within ~30 s trips TranslucentTB's failsafe (taskbar falls back to the accent
  color, from `Explorer\Accent\AccentPalette`). The script samples the taskbar color before/after and
  only flags a change from a custom color to a stock one, and only if a styling tool was running
  (without one, the accent shade can drift between restarts). Styling tools that died are relaunched.
  `pins --restart-cooldown <s>` (MCP: `restartCooldown`) spaces out restarts; `pin`, `unpin`, `reorder` and `refresh` take `--cooldown <s>`. Context changes (TranslucentTB going clear on the
  desktop) are normal and not flagged.
- MCP clients start servers with a trimmed environment (no `ProgramData`/`WINDIR`): resolve folders via
  `[Environment]::GetFolderPath`, never env vars.
- All-users Start Menu shortcuts (`C:\ProgramData\…`) need admin; reported as `skipped`.
- Console apps (PowerShell, cmd) run inside Windows Terminal when it's the default terminal, so their
  running button is Terminal's. Use a GUI app to test.

## Safety around pin-list writes
- Writers parse `Favorites` and `FavoritesResolve` strictly (`Taskband.Strict`): every record must
  parse, `Favorites` must end in a single `0xFF`, and both lists must have the same length. Anything
  else throws instead of rewriting a list that was only partly understood.
- `Invoke-WithExplorerStopped` snapshots both values first. If the action throws, the snapshot is
  written back before Explorer restarts.
- Backups in `%LOCALAPPDATA%\iconwright\backups\`: `original\` (once, before the first change) and
  `last\` (before every change; written to `pending\` and promoted only if the change succeeds).
  Each holds `taskband.reg` (reg export) and `TaskBar\` (the pinned shortcuts). Older versions wrote
  `taskband-<stamp>.reg` + `TaskBar-folder-<stamp>`; `restore-pins --from original` still reads those.
- `reg.exe` prints its status to stderr, which PowerShell 5.1 turns into an error under
  `$ErrorActionPreference = 'Stop'`; `Invoke-Reg` runs it with `Continue` and checks the exit code.
- Mutating commands hold the named mutex `Local\iconwright-change`.
- After the restart, `Wait-Taskbar` polls for `Shell_TrayWnd`. Explorer is started by hand only if
  Windows didn't restart it within 8 s (a second `explorer.exe` would open a File Explorer window).
- `state.json` holds each changed item's original icon for `restore` / `restore-all`.

## Taskbar order
Pin order = entry order in `Favorites` (with `FavoritesResolve` kept in the same order). `reorder`
rewrites both while Explorer is stopped (one restart). Verified: Explorer keeps the new order.

## Desktop icons (all live, no restart)
- Reached like the taskbar shell object: `ShellWindows.FindWindowSW(SWC_DESKTOP)` → `IShellBrowser` →
  `QueryActiveShellView` → `IFolderView2`. Works cross-process (COM marshals the PIDLs).
- Items: `ItemCount/Item` + `SHGetNameFromIDList` (desktop child PIDLs are absolute). Positions:
  `GetItemPosition` / `SelectAndPositionItems(SVSI_POSITIONITEM)`; auto-arrange is turned off first.
  Positions are quantized to the icon grid (`GetSpacing`, e.g. 150×210 px at 200% scale) even with
  "align to grid" off.
- Size: `SetViewModeAndIconSize(FVM_ICON, px)`. Flags: `SetCurrentFolderFlags` (FWF_AUTOARRANGE,
  FWF_SNAPTOGRID, FWF_NOICONS).
- Persist: explorer saves the desktop layout only on a clean exit, so we call `IShellView::SaveViewState`
  after changes and before every forced Explorer restart.
- Icons: `.lnk` → IconLocation; `.url` → `IconFile`/`IconIndex`; folders → `desktop.ini`
  `IconResource` (+ReadOnly on the folder, Hidden+System on the ini); system icons (This PC,
  Recycle Bin…) → `HKCU\…\Explorer\CLSID\{clsid}\DefaultIcon` (Recycle Bin also `empty`/`full`) +
  `SHCNE_ASSOCCHANGED`. Plain files can't have per-file icons (type-based).
- System icon visibility: `HKCU\…\HideDesktopIcons\NewStartPanel\{clsid}` = 1 hidden / 0 shown, then
  refresh the desktop view.
- Label text color isn't configurable (always white with shadow).


---

# Changelog

## Unreleased

- **Fix:** restyling an app no longer changes pinned shortcuts that only launch through it with arguments, such as Steam games (which run `steam.exe steam://rungameid/…`) or browser profile shortcuts. Found on screen: restyling Steam also changed a pinned Steam game.
- `iconwright report` prints system details and a self-test as Markdown for test reports, without app names, paths or the user name.
- `iconwright mcp` starts the MCP server, and the package is ready for npx as `iconwright` (not published yet).
- Screenshots explain a locked or sleeping screen instead of failing with "The handle is invalid".
- Docs: test prompts for macOS, Linux and Windows with the stock taskbar; issue and pull request templates; what doesn't work while the screen is locked.

## 0.2.0 (2026-10-29)

A design release: iterate on icons cheaply, with your agent or by hand, and see them in place before using them.

**Design**

- `design_icons`: compare artwork (rows) and styles (columns) in one small grid; pick a cell like "B2".
- `search_icons` returns a numbered contact sheet, icon licenses, paging, set filters and a `palette` filter (single-color or multicolor sets).
- `preview_icon`: mockups on a Windows taskbar, Start menu, desktop and File Explorer, a browser tab, the macOS Dock, iOS and Android, plus true pixel sizes. On Windows, your own pinned apps sit around the icon.
- Styles are one string everywhere: `color=white bg=#2d5ba6 shape=squircle shadow`. New: gradient backgrounds, the squircle shape and a soft shadow.
- `app:<App name>` uses an installed app's current icon as a source (Windows).
- Export to macOS `.icns`, a favicon and web-app set (with a maskable icon and manifest) and PNG sets. `.ico` files now include 20 and 40 px images for 125% and 250% scaling.
- The studio: a visual editor in the browser, online or local (`iconwright studio`, or the `open_studio` tool). Local studio can apply icons to apps.

**Windows**

- `taskbar_pins`: pin, unpin and reorder in one call and one Explorer restart, with a dry run.
- Changes from agents and the studio run one at a time, start to finish.

**For agents**

- 20 tools instead of 27, with a 25% smaller tool list. Tool definitions live in one table that also generates the docs.
- MCP prompts: design-icon, restyle-taskbar, tidy-desktop, undo-everything.
- A rewritten skill with a design guide, `llms.txt`, `llms-full.txt`, and every docs page as Markdown.

**Renamed or merged tools**: `list_apps` and `app_info` → `find_apps`; `app_set_icon` → `app_apply_icon` with `icon`; `taskbar_pin`, `taskbar_unpin` and `taskbar_reorder` → `taskbar_pins`; `app_restore_icons`, `desktop_restore_icons` and `restore_all_icons` → `restore_icons`; `desktop_icon_size`, `desktop_options` and `desktop_system_icons` → `desktop_settings`; `desktop_layout_save` and `desktop_layout_load` → `desktop_layout`; `desktop_move` takes a list; `make_sheet` → `design_icons`. Style options are now one `style` string.

**Fixes**: recoloring leaves SVG masks and clip paths alone and recolors gradient fills; artwork with an opaque background keeps it; gradients span the whole icon at any angle, as in CSS; edited source files are never served from a stale cache.

## 0.1.0 (2026-10-27)

First public version.

- Make `.ico` icons (256 to 16 px) from Iconify names, SVG, PNG, JPEG, WebP or existing `.ico` files, with recolor, backplate, padding and preview images. Works on Windows, macOS and Linux.
- Windows: change app icons on the taskbar, Start Menu and pinned shortcuts; pin, unpin and reorder taskbar apps; move, arrange, resize, re-icon, show and hide desktop icons; save and load desktop layouts.
- Undo: `restore <app>`, `restore --all`, `desktop restore`, and `restore-pins` (pin list backups taken before every change).
- Safety: pin-list writes refuse unfamiliar layouts, roll back on failure, and run one at a time. `doctor` checks a PC before use.
- Interfaces: CLI, MCP server (stdio), Claude Code plugin with a skill, and Codex via MCP.


---

# Contributing

The most useful contribution right now is **testing on a computer that isn't the developer's**. iconwright has been tested on one Windows 11 PC with a customized taskbar (StartAllBack). Everything else is unknown: the stock Windows 11 taskbar, Windows 10, macOS, Linux, several monitors, non-English Windows.

This page has ready-made prompts: paste one into your AI agent (Claude Code, Codex, Cursor or any agent with a terminal), and it installs iconwright, runs a test plan, and writes a report for you to send back.

## How to send findings

Pick whichever suits you. All three are welcome.

| Way | Best for | How |
| --- | --- | --- |
| **Test report issue** | Most testers | [Open a test report](https://github.com/JayceeGupta/iconwright/issues/new?template=test-report.yml), paste the report your agent wrote, attach screenshots. |
| **Report as a pull request** | Keeping reports with the code | Add your report as `test-reports/<date>-<system>.md` (for example `2026-11-02-windows10.md`) and open a pull request. |
| **Fix as a pull request** | When you know the fix | Open a pull request with the change and the report that shows the problem. |

The maintainer reads every report and pull request, and may write the fix their own way rather than merging yours as is. Either way, your report is what makes the fix possible, and it's credited in the changelog.

Before sharing, check your report and screenshots for anything private. `iconwright report` leaves out app names, file paths and your user name, but screenshots of a taskbar or desktop show your apps and files.

## Test prompts

Each prompt is self-contained. It tells the agent what to test, what it may change, and to put everything back. Changes that restart Explorer (the taskbar blinks and open File Explorer windows close) always need your OK first.

### macOS or Linux

Only the design features run here (search, compare, preview, export, studio); the taskbar and desktop features are Windows-only.

```text
Help me test iconwright (https://github.com/JayceeGupta/iconwright), an MCP server and CLI
for designing icons. Run this plan and write a report. Only create files inside one new
temporary folder; change nothing else on this computer.

1. In a new temporary folder: git clone the repo, run npm install, then run
   `node bin/iconwright.mjs report` and keep its output for the report.
2. Command line. Run each, then open every image it makes and look closely:
   - node bin/iconwright.mjs search rocket --sheet search.png
   - node bin/iconwright.mjs design ph:rocket-launch-fill tabler:rocket --styles "color=white bg=#2d5ba6 shape=squircle|color=#e9c46a bg=#1f2228 shape=circle" --out grid.png
   - node bin/iconwright.mjs preview ph:rocket-launch-fill --style "color=white bg=#2d5ba6 shape=squircle" --scenes taskbar,start,desktop,explorer,browser,dock,ios,android,sizes --scale 2 --out scenes.png
   - node bin/iconwright.mjs make ph:rocket-launch-fill --style "color=white bg=#2d5ba6 shape=squircle" --formats ico,icns,web,pngset --out out
   Note anything wrong: errors, clipped or missing text, misplaced icons, wrong colors,
   blank cells. On macOS, open out/*.icns in Preview and check it shows every size.
3. MCP. Add a stdio MCP server to yourself that runs `node <clone>/bin/iconwright-mcp.mjs`
   (if you can't add servers to yourself, use the MCP SDK from a small Node script).
   Check that exactly these tools are listed: search_icons, design_icons, preview_icon,
   make_icon, open_studio. Call each of the first four once and look at the images.
4. Studio. Run `node bin/iconwright.mjs studio --no-open`, open the printed link, search,
   pick an icon, change color and shape, click "Show 6 ideas", download a .ico and the
   website icons. Note anything broken or confusing. Stop it with Ctrl+C afterwards.
   If you can't use a browser, skip this step and say so in the report.
5. Write the report as iconwright-report.md using the template at
   https://iconwright.guptajayam.com/docs/contributing#report-template, with the
   `report` output, what worked, what didn't (exact commands and errors) and the images
   that looked wrong. Then tell me where the report and images are, and delete the
   temporary folder only after I've said I've sent them.
```

### Windows 10 or 11 with the stock taskbar

This is the most valuable test: iconwright edits how Windows keeps pinned apps, and that has only been tested with StartAllBack. Everything the plan changes is put back at the end.

```text
Help me test iconwright (https://github.com/JayceeGupta/iconwright), an MCP server and CLI
that designs icons and changes the Windows taskbar and desktop. Run this plan and write a
report. Rules:
- Ask me before every step marked RESTART: it restarts Windows Explorer, so the taskbar
  blinks and open File Explorer windows close. Skip it if I say no.
- Put everything back at the end, and prove it by comparing before and after.
- Screenshots may show my apps; ask before including them in the report.

1. Set up: git clone the repo into a new folder, run npm install, then
   `node bin/iconwright.mjs report` (keep the output) and `node bin/iconwright.mjs doctor`.
   If doctor reports a problem, stop and report it.
2. Record the starting state: `node bin/iconwright.mjs status` (pinned apps in order) and
   `node bin/iconwright.mjs desktop list`. Save both outputs to before.json.
3. Design (no changes to Windows): run the four commands in step 2 of the macOS/Linux
   prompt at https://iconwright.guptajayam.com/docs/contributing#macos-or-linux and check
   the images, plus `node bin/iconwright.mjs preview app:<one of my pinned apps> --scenes taskbar,start --out mine.png`.
4. App icon: pick one pinned app that isn't important to me. Run
   `node bin/iconwright.mjs apply "<app>" --source app --style "color=#e9c46a bg=#1f2228 shape=squircle"`,
   take `node bin/iconwright.mjs capture taskbar`, check that only that app's icon changed
   (and the Start menu entry), then `node bin/iconwright.mjs restore "<app>"` and capture again.
5. Pins, dry run: `node bin/iconwright.mjs pins --pin Notepad --order Notepad --position 1 --dry-run`.
   Check the predicted order makes sense.
6. RESTART: `node bin/iconwright.mjs pins --pin Notepad --order Notepad --position 1`.
   Capture the taskbar: is Notepad pinned in second place and did everything else stay?
   Did the taskbar come back normally? Note how long it took.
7. RESTART: `node bin/iconwright.mjs pins --unpin Notepad`. Compare `status` with before.json:
   the pinned apps and their order must be identical.
8. Desktop: `node bin/iconwright.mjs desktop save before-desktop.json`, then
   `node bin/iconwright.mjs desktop arrange --by type --corner top-right`, capture the desktop,
   then `node bin/iconwright.mjs desktop load before-desktop.json` and compare
   `desktop list` with before.json.
9. Final check: `node bin/iconwright.mjs restore --all`, then compare status and desktop list
   with before.json once more. Anything different is a finding.
10. Write the report as iconwright-report.md using the template at
    https://iconwright.guptajayam.com/docs/contributing#report-template. Include exact
    commands, outputs and errors for anything that failed, and tell me where it is.
```

For **Windows with several monitors**, add to the prompt: “In step 8, run the arrange on monitor 1 as well (`--monitor 1`), and check icons on the other monitor didn't move.” For **non-English Windows**, add: “Note my Windows display language in the report, and check that app names in `status` and `apps` look right.”

### Through the agent tools instead of the command line

To test the MCP server the way agents use it, add this to either prompt: “Do the steps with the iconwright MCP tools instead of the command line where a tool exists (taskbar_status, app_apply_icon, restore_icons, taskbar_pins with dryRun, desktop_layout, desktop_arrange, capture), and note any tool description that was unclear or any result that was hard to use.”

## Report template

```markdown
# iconwright test report: <your system, e.g. Windows 10 22H2, stock taskbar>

## Environment
<paste the output of `node bin/iconwright.mjs report`>
- Taskbar: stock / StartAllBack / ExplorerPatcher / other: ...
- Monitors: ..., display scaling: ...%, Windows display language: ...

## What I tested
- [ ] Design commands (search, design, preview, make)
- [ ] MCP server
- [ ] Studio
- [ ] App icon apply and restore
- [ ] Pins: dry run, pin and reorder, unpin
- [ ] Desktop: save, arrange, load
- [ ] Everything back to the starting state (before/after identical)

## What went wrong
For each problem: what I ran, what I expected, what happened (exact error), screenshot.

## What was confusing
Docs, messages or results that were unclear.

## Anything else
```

## Changing the code

```bash
git clone https://github.com/JayceeGupta/iconwright
cd iconwright && npm install
npm test                      # the test suite (any OS)
npm run site:build            # builds the website into site/dist
node scripts/dev/serve-site.mjs  # serves it at http://127.0.0.1:4318
```

- [How it works](how-it-works.md) explains the parts; [Windows internals](windows-internals.md) has the details of the pinned-apps format and Explorer. Read it before changing anything about pins.
- MCP tools are defined in one table in `src/tools.mjs`; the [tool reference](tools.md) is generated from it.
- Test changes to pins, icons or the desktop end to end on a real PC, and put everything back afterwards.
- Keep the docs' voice: short sentences, plain words, what the user sees.