iconwright
View Markdown

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#

Install#

Claude Code#

Run these two commands inside Claude Code:

/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#

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:

[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:

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

Let your agent do it#

Copy the 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 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:

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#