# How it works

This page explains how iconwright does each thing, in plain terms. For byte-level details, see Windows internals.

The big picture#

 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 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; 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.

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:

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#