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:

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