generate-app-icons

name

generate-app-icons

description

Generate four app-logo candidates for user selection, then turn the chosen direction into a cohesive production-ready icon family for macOS, Windows desktop/MSIX, and the Web. Use when Codex needs to design an app logo or icon, present visual alternatives, create transparent and solid icon masters, make a macOS menu-bar template or Dock icon, build .icns/.ico/favicon files, or export Microsoft Store/MSIX visual assets.

Generate App Icons

Use a mandatory two-phase workflow: propose four logos, pause for the user's selection, then build the platform assets from the selected candidate. Never choose a candidate on the user's behalf.

Phase 1: Propose four candidates

1. Collect the app name, purpose, symbol/concept, desired style, palette, and optional solid background color.
2. Favor simple, distinctive geometry that remains recognizable at 16 px. Avoid text, tiny details, mockups, and screenshots.
3. Preview the four prompts without an API request when useful:

python3 scripts/generate_app_icons.py propose \
  --app-name "LumaWorks" \
  --purpose "Local-first AI short-drama studio" \
  --concept "A luminous frame merging with a film strip" \
  --style "Refined, cinematic, geometric" \
  --palette "violet, electric blue, warm white" \
  --solid-color "#17132B" \
  --out /absolute/path/to/lumaworks-icons \
  --dry-run

4. Read a rotated, private key from the environment. Never place it in a prompt, command argument, file, or response:

export HAODUOTOKEN_API_KEY="..."

5. Run the same propose command without --dry-run, using a new or empty output directory. It makes four image requests, engineers transparency, and creates:
   • candidates/candidate-1.png through candidate-4.png
   • candidate-preview.png
   • selection.json
6. Display candidate-preview.png to the user and ask them to choose 1, 2, 3, or 4.
7. Stop. Do not run build, infer a preference, or auto-select while waiting for the user's answer.

In Codex desktop, show the preview with an absolute local path:

![Four logo candidates](/absolute/path/to/candidate-preview.png)

Phase 2: Build the selected direction

After the user explicitly selects a candidate, run:

python3 scripts/generate_app_icons.py build \
  --out /absolute/path/to/lumaworks-icons \
  --candidate 2

The build phase reads the saved brief and selected transparent logo, makes only the Dock and menu-bar requests, then exports the complete macOS, Web, Windows desktop, and Windows MSIX packages. It records the selected candidate in manifest.json.

Inspect preview.png, especially the 16 px and menu-bar samples. If the selected concept becomes unclear at small sizes, explain the issue and offer to return to Phase 1; do not silently switch candidates.

CLI options

Shared generation defaults are https://byte.haoduotoken.com/v1/images/generations, gpt-image-2, 1024x1024, and high quality.

• propose --api-base, --model, --size, --quality: Set request behavior saved in selection.json.
• propose --chroma-color, --chroma-tolerance: Control engineered background removal.
• build --api-base, --model, --size, --quality: Optionally override saved request settings.
• build --candidate 1..4: Required explicit user selection.
• build --skip-icns: Keep the iconset but skip iconutil; useful off macOS.
• Both phases support --dry-run; build --dry-run requires an existing proposal workspace.

The script requires Python 3 and Pillow. macOS .icns creation additionally requires iconutil:

python3 -m pip install Pillow

Transparency and quality

gpt-image-2 does not provide native transparent output. Both phases request a uniform chroma background, remove only edge-connected background pixels, feather antialiased edges, remove color spill, and validate alpha and safe margins.

Treat a failed background or safe-margin validation as a real generation failure. Never disable validation or deliver an opaque file renamed as PNG.

Read references/icon-specs.md for exact filenames, dimensions, MSIX qualifiers, candidate directions, and validation rules.

Security

• Read credentials only from HAODUOTOKEN_API_KEY.
• Do not add an API-key CLI flag.
• Redact the active key from transport errors.
• Store public endpoints, prompts, hashes, dimensions, and the selected candidate; never store request headers or credentials.