---
name: macos-folder-icons
description: Apply or remove custom macOS Finder folder icons using the hidden Icon carriage-return file and Finder custom-icon flag. Use when Codex needs to change Desktop folder icons, batch-apply a custom image to folders, generate and apply the built-in pentagram folder icon, restore default folder icons, or troubleshoot macOS folder icon scripting.
---


# macOS Folder Icons

## Quick Start

Use `scripts/apply_folder_icon.sh` for the fragile parts of the workflow. It builds a valid `.icns` resource, writes each folder's hidden `Icon\r` resource file, sets the Finder custom-icon flag, verifies the result, and restarts Finder unless told not to.

Common commands:

```bash
# Apply the built-in pentagram icon to all top-level folders on the Desktop.
bash /Users/tec/.codex/skills/macos-folder-icons/scripts/apply_folder_icon.sh --target "$HOME/Desktop" --style pentagram

# Apply a custom image to all top-level folders in a directory.
bash /Users/tec/.codex/skills/macos-folder-icons/scripts/apply_folder_icon.sh --target "/path/to/parent" --image "/path/to/icon.png"

# Apply a custom image to specific folders only.
bash /Users/tec/.codex/skills/macos-folder-icons/scripts/apply_folder_icon.sh --image "/path/to/icon.png" --folder "/path/to/folder one" --folder "/path/to/folder two"

# Remove custom icons and return folders to default Finder icons.
bash /Users/tec/.codex/skills/macos-folder-icons/scripts/apply_folder_icon.sh --target "$HOME/Desktop" --restore
```

## Workflow

1. Confirm the request is for macOS Finder folder icons, not app icons or web/UI icons.
2. Prefer the script over retyping the workflow.
3. Use `--target "$HOME/Desktop"` for "all folders on my Desktop"; the script applies to top-level folders inside the target directory.
4. Use `--folder` for explicit folders, repeating the flag for multiple folders.
5. Use `--image` for a user-supplied image, or `--style pentagram` when the user wants the saved pentagram look.
6. Avoid `tell application "Finder" to update ...`; it can clear freshly written icon resources on some macOS versions. Let the script restart Finder after verification.
7. Report the changed count, failed count, and any skipped package bundles.

## Notes

- Required macOS tools: `swift`, `sips`, `iconutil`, `xxd`, `Rez`, `SetFile`, and `GetFileInfo`.
- The script intentionally skips package-like folders such as `.app`, `.pkg`, `.bundle`, and `.framework` unless explicit `--folder` paths are supplied.
- Custom folder icons are stored as a hidden file named `Icon\r` inside the folder plus the folder's custom-icon Finder flag.