`README.md`

65 lines
# opened-tagger

Marks **everything you've ever opened or launched** on this Mac with the blue
Finder tag. In any Finder window, a **blue dot = you've opened this before**;
**no dot = never touched**. Your "what haven't I read yet?" system.

## How it works

macOS Spotlight records `kMDItemUseCount` (times opened) on every indexed file
and app. `tag-opened.py` asks Spotlight for items with use-count > 0 and adds the
system **Blue** tag to each, preserving any tags already present. Pure built-ins
(`mdfind`, `xattr`, Python stdlib) — nothing to install.

## Usage

```sh
python3 tag-opened.py            # tag opened items in the default surfaces
python3 tag-opened.py --dry-run  # preview only, change nothing
python3 tag-opened.py --untag    # remove the Blue tag (full undo)
python3 tag-opened.py --dirs ~/Desktop ~/Projects   # custom surfaces
```

Default surfaces: `~/Desktop`, `~/Documents`, `~/Downloads`, `~/Projects`
(skipping `node_modules`, `.git`, caches, Trash) + all launched apps Mac-wide.

## Make it automatic (re-tag newly-opened items every 30 min)

The LaunchAgent is at `~/Library/LaunchAgents/com.steve.opened-tagger.plist`.
Enable it yourself (installing a background agent is intentionally gated):

```sh
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.steve.opened-tagger.plist
launchctl list | grep opened-tagger    # confirm a PID appears
```

Disable later:

```sh
launchctl bootout gui/$(id -u)/com.steve.opened-tagger
```

## Literal light-blue TEXT (the viewer)

Finder only does the dot. For actual blue *text*, run the viewer — a local web
page where opened items render in **light blue** and never-opened in **bold white**:

```sh
python3 ~/Projects/opened-tagger/viewer.py    # prints a http://127.0.0.1:PORT/ URL
```

Open the printed URL. Live from Spotlight, has a filter box, groups by surface
(Desktop / Documents / Downloads / Projects / Apps) with opened-count per group.
It's a separate window, not the real Finder — that's the tradeoff for true text color.

## Known limitations (honest)

- **Blue dot, not blue text.** Finder renders tags as a colored dot/pill next to
  the filename, never as recolored text — macOS has no setting for text color.
  For literal light-blue text you'd need a custom viewer window (not real Finder).
- **SIP-protected system apps can't be tagged.** Safari, Mail, and other Apple
  apps in `/System/Applications` block attribute writes; the tag silently no-ops.
  User-installed apps (in `~/Applications`, `/Applications`) tag fine.
- **"Opened" = opened by an app Spotlight noticed.** Quick Look previews and some
  background reads may not bump the use-count.