Open Folder Icons

Open Folder Icons is a free, offline macOS menu-bar app that automatically gives folders recognizable custom icons based on their names.

It watches folders you choose, classifies new or renamed folders with local rules, renders a colored folder icon with an SF Symbol overlay, and applies it using macOS' native custom-icon support.

No accounts. No telemetry. No subscriptions. No cloud AI calls.

Screenshots

Features

• Automatically styles new and renamed folders in watched locations
• Uses a local, editable taxonomy in JSON
• Generates stable color/icon choices from folder names
• Re-rolls individual folders when a generated choice is not ideal
• Lets users manually edit a folder's color and symbol
• Shows a preview grid before applying icons
• Adds Finder Services for right-click edit, re-roll, and reset
• Optionally keeps watched Finder windows in icon view
• Can launch automatically at login
• Runs as a lightweight menu-bar app

Requirements

• macOS 13 or newer
• Xcode command line tools or Xcode
• Swift 6-compatible toolchain

Install From Source

Clone the repository, then build the app bundle:

git clone <repo-url>
cd OpenFolderIcons
Scripts/package-app.sh
open .build/OpenFolderIcons.app

For local development, you can also run the executable directly:

swift run OpenFolderIcons

Unsigned Downloads

Releases may include an unsigned .zip build for convenience. Unsigned builds are not notarized by Apple, so macOS may block the first launch as coming from an unidentified developer.

To open an unsigned build, Control-click or right-click OpenFolderIcons.app, choose Open, then confirm the warning.

To create an unsigned release zip:

Scripts/package-release.sh

Usage

Open the app and use the menu-bar folder icon.

• Preview Icons... shows sample generated icons.
• Edit Folder Icon... opens a manual editor for one folder.
• Settings... lets you choose watched folders and enable icon-view preservation.
• Launch at login can be enabled from Settings.
• Apply Icons Now refreshes all folders in watched locations.
• Re-roll Icons In Watched Folders gives watched folders a new deterministic variant.
• Reset Icons In Watched Folders removes custom icons from watched folders.

Finder integration is available from the right-click Services submenu:

• Re-roll Folder Icon
• Edit Folder Icon
• Reset Folder Icon

macOS may take a moment to register Services after the first launch.

Permissions

The app changes custom icons only for folders you select or watch.

If you enable Finder refresh behavior or use Finder Services, macOS may ask for permission to control Finder. This is used to repaint Finder windows after icon changes and to preserve icon view when requested.

How Matching Works

Folder matching rules live in:

Sources/FolderIconCore/Resources/icon-rules.json

Each rule can include:

• id: stable category identifier
• displayName: category label
• keywords: folder-name keywords to match
• color: default hex color
• symbolName: default SF Symbol overlay
• colors: optional category palette
• symbolNames: optional SF Symbol pool

The first matching rule wins. If no rule matches, the app uses a fallback icon pool. Generated choices are deterministic, so the same folder keeps the same appearance until it is re-rolled.

Development

Run tests:

swift test

Build a local .app bundle:

Scripts/package-app.sh

The project is split into:

• FolderIconCore: matching, rendering, preferences, watching, and icon application
• FolderIconApp: menu-bar UI and Finder Services
• icon-rules.json: the local folder-name taxonomy

Icon Assets And Licensing

Open Folder Icons uses SF Symbols by name at runtime. SF Symbols are provided by Apple for use on Apple platforms and are not copied into this repository.

Future bundled icon packs should be permissively licensed and documented before inclusion.

Built with help from OpenAI Codex.

Roadmap

• Top-level Finder context menu integration with Finder Sync
• Custom imported overlays
• Optional local or bring-your-own-key AI suggestions