Finder Tags for VS Code

See your macOS Finder tag colors in the VS Code Explorer. Tag a folder Red in Finder and it shows up red in VS Code; change it to Blue in Finder and VS Code follows. Finder stays the single source of truth, so there is nothing to assign or keep in sync inside VS Code.

macOS only. The extension reads metadata that Finder stores on macOS file systems. On other platforms it stays inactive.

Each folder was tagged in Finder (Blue, Gray, Green, Yellow, Purple, Red and Orange); notes and scripts have no tags. Hovering paper shows Finder tags: Submission, Red.

Features

• Colors Finder-tagged folders (and, if you want, files) in the Explorer with their Finder color.
• Adds a small ● badge, so colors that come from Finder stand out from Git status colors.
• Lists every tag in the tooltip, for example Finder tags: Research (Red), Blue.
• Follows changes made in Finder, usually within a second for items inside the workspace.
• Reads lazily: only folders you actually look at are read, so large repositories stay fast.
• Reads metadata and nothing else. It never changes tags and makes no network requests.

Requirements

• macOS. The extension uses only tools that ship with macOS (find, xattr, mdls). The tag format it reads has been in use since tags were introduced in OS X 10.9; development and testing happen on macOS 27.2.
• VS Code 1.90 or later. The automated tests pass on 1.90.0 and on 1.144.
• Local files. In a remote window (SSH, Dev Containers, WSL) VS Code runs the extension on the remote host, so it only works when that host is a Mac.

Supported colors

Custom tags work too. A tag named "Research" that you colored red in Finder shows up red. Tags without a color appear in the tooltip only.

When an item has several tags, the first tag that has a color, in the order Finder stores them, decides the Explorer color. Every tag still appears in the tooltip and in the diagnostics report.

Settings

Changing the colors

Each Finder color is a theme color, so you can override it in settings.json, globally or per theme:

"workbench.colorCustomizations": {
  "finderTags.yellow": "#C8A000",
  "[Default Light Modern]": {
    "finderTags.yellow": "#8A6A00"
  }
}

The defaults follow Apple's system colors. Light and high-contrast themes get darker or brighter variants so that labels stay readable; every default reaches a contrast of at least 4:1 against the default Explorer background of its theme type.

Commands

How Finder tags are read

Finder stores an item's tags in an extended attribute named com.apple.metadata:_kMDItemUserTags. The value is a binary property list holding an array of strings such as "Red\n6" or "Research\n6": the tag name, a newline, and the color number from the table above. The extension reads this attribute directly.

• When VS Code needs the decoration of an item, the extension scans the item's folder with one /usr/bin/find process that lists only the children carrying this attribute. Requests that arrive together, such as all the children of a folder you expand, share a single process.
• Only tagged items are read, with /usr/bin/xattr. The property list is decoded inside the extension, with no extra process or dependency.
• Results are cached per folder. A re-check lists the tagged children again and re-reads an item only when its status-change time moved, which happens whenever its tags are edited.
• In long sessions with many folders, folders that are no longer on screen stop being re-checked until VS Code needs them again.

Spotlight (mdls) is not used for decorations. It drops the colors and has nothing to report for items it has not indexed. The diagnostics report shows its answer next to the attribute's, for comparison.

The format, and how the color numbers were verified, are described in docs/FINDER_METADATA.md. The code layout is in docs/ARCHITECTURE.md.

Privacy

Finder Tags works entirely on your Mac.

• No telemetry, analytics or crash reporting.
• No network requests of any kind.
• File names, paths and tags never leave your machine. They appear only in the local Finder Tags output channel, when you run the diagnostics command or raise the log level.
• The extension only reads. It never writes tags, files or settings.
• It runs only Apple's own command-line tools (/usr/bin/find, /usr/bin/xattr, /usr/bin/mdls), by absolute path and without a shell. File names are passed as separate arguments and are never interpreted as commands.

Limitations

• Name color, badge and tooltip. VS Code's file decoration API can color an item's name and add a short badge and a tooltip. It cannot recolor folder icons or draw Finder's tag dots, and extensions cannot inject CSS into VS Code. Finder Tags uses the supported API only.
• One color per item. When several tags have colors, the first one is used.
• Decorations are shared with other extensions. When Git (or another extension) also decorates an item, VS Code shows a single name color, taken from the extension that registered its decorations most recently, and joins the badges into one (for example M, ●) drawn in that color. A tagged folder keeps its Finder color when Git colors spread up from changed files inside it; VS Code then shows its own "contains emphasized items" dot and tooltip for that folder. If Git colors get in the way, set git.decorations.enabled to false.
• VS Code settings. Colors appear only while explorer.decorations.colors is on, and badges only while explorer.decorations.badges is on. Both are on by default.
• Some changes take longer. Tag edits inside the workspace usually arrive through VS Code's file watcher within a second. Edits on workspace root folders, in folders excluded by files.watcherExclude (such as node_modules), and on files outside the workspace show up at the next periodic re-check, when the window regains focus, or after Finder Tags: Refresh.
• Very large sessions. Once more than 200 folders are being re-checked, the extension asks VS Code every 10 minutes to request its decorations again, so it can stop re-checking folders that are no longer on screen. The Explorer colors may blink once when that happens.
• Stored colors. The extension shows the color stored with each item's tag. If you change a tag's color in Finder's settings, items whose tags Finder has not rewritten keep the old color. Some sync tools (Google Drive, for example) store tags without a color number; such tags get a color only when the name is one of the seven standard English color names.
• Legacy labels. Items that carry only a pre-tags Finder label (OS X 10.8 and earlier) and no tags are not decorated.
• Local files only. Virtual file systems, and remote hosts that are not Macs, have no Finder tags.

Troubleshooting

1. Right-click the item in the Explorer and choose Show Finder Tags, or run Finder Tags: Show Finder Tags for Current File. The Finder Tags output channel then shows the raw attribute bytes, the decoded tags, the color the Explorer should use and, when there is none, the reason.
2. If tagged items show the ● badge but no color right after you installed or updated the extension, run Developer: Reload Window (the extension offers this itself). VS Code applies an extension's colors only when a window starts.
3. Check that explorer.decorations.colors and explorer.decorations.badges are on.
4. Run Finder Tags: Refresh.
5. For more detail, run Developer: Set Log Level..., choose Finder Tags and select Debug or Trace. Scans and tag changes are then logged to the same output channel.
6. From a terminal, a clone of this repository can print the same report: npm run inspect-tag -- "/path/to/item".

Reporting an issue

Please open an issue at https://github.com/juanfraire/finder-tags-vscode/issues and include:

• macOS version, VS Code version and Finder Tags version;
• what you expected and what you saw, with steps to reproduce;
• the diagnostics report for an affected item.

The report contains the item's path and tag names. Remove anything you would rather not share before posting it.

Installation

From the Visual Studio Marketplace: search for "Finder Tags" in the Extensions view, or run

code --install-extension juanfraire.finder-tags-vscode

From a .vsix file: download one from the GitHub releases (pick darwin-arm64 for Apple silicon, darwin-x64 for Intel) or build one as described below, then run code --install-extension finder-tags-vscode-0.1.0.vsix, or use Extensions: Install from VSIX... in the Command Palette.

Development

You need Node.js 22 LTS or newer and npm.

npm install
npm run compile

Then open this folder in VS Code and press F5 (configuration Run Extension). A second VS Code window, the Extension Development Host, opens with the extension loaded. Open a folder that contains Finder-tagged items in that window.

The manual test procedure is in docs/MANUAL_TESTING.md.

Packaging

The package is built with @vscode/vsce:

npm run package   # writes finder-tags-vscode-0.1.0.vsix
npx vsce ls       # lists the files that go into the package

Release steps are in CONTRIBUTING.md.

Contributing

Bug reports, ideas and pull requests are welcome. See CONTRIBUTING.md.

License

MIT