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

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: a short index of the docs with the key usage rules.
• /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.
• The MCP tool reference 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:

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#

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

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.