LaunchServices Health (macOS)

When to Use This Skill

Platform Guard

This skill is macOS-only. The lsregister binary, launchservicesd daemon, and the LaunchServices database are Darwin-specific. Refuse to act if uname -s is not Darwin.

test "$(uname -s)" = "Darwin" || { echo "macos-plugin: not Darwin, refusing"; exit 1; }

Core Expertise

LaunchServices is the macOS subsystem that maps documents and URL schemes to applications. State is held by launchservicesd and persisted to a binary database. Two failure modes matter:

1. DB bloat — over months of uptime and app churn (Homebrew updates, Xcode reinstalls, Wine/CrossOver bottle creation, Electron app upgrades), the DB accumulates stale bundle records and duplicate claims. The bigger the DB, the slower lsregister -dump runs and the more memory launchservicesd holds.
2. Daemon wedge — launchservicesd can spin at high CPU when a misbehaving process repeatedly registers/unregisters bundles. WindowServer makes synchronous XPC calls into launchservicesd for icon and document-handler lookups; a wedged daemon manifests as a frozen GUI.

The diagnostic answer is always: measure first, rebuild only if warranted. Rebuild (lsregister -kill -r ...) takes minutes, makes every app's "open with" disappear briefly, and rebuilds the DB from scratch — only do it when the metrics justify it.

Where the bits live

Quick Snapshot

The reference script ls-stats produces a one-page health snapshot. Install at ~/.local/bin/ls-stats (mode 0755):

#!/usr/bin/env bash
# ls-stats: macOS LaunchServices DB + launchservicesd health snapshot
set -euo pipefail

[ "$(uname -s)" = "Darwin" ] || { echo "not Darwin" >&2; exit 1; }

LSREG=/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister
PID=$(pgrep -x launchservicesd) || { echo "launchservicesd not running" >&2; exit 1; }

DUMP=$(mktemp); trap 'rm -f "$DUMP"' EXIT
"$LSREG" -dump >"$DUMP" 2>/dev/null

echo "=== launchservicesd ==="
ps -o pid,rss,etime,command -p "$PID" | sed 's/^/  /'

echo
echo "=== LaunchServices DB ==="
wc -c <"$DUMP" | awk '{printf "  size:    %d bytes (%.1f MB)\n", $1, $1/1048576}'
printf "  bundles: %d\n" "$(grep -c '^bundle id:' "$DUMP")"
printf "  claims:  %d\n" "$(grep -c '^claim '    "$DUMP")"
printf "  records: %d\n" "$(grep -c '^----'      "$DUMP")"

echo
printf "=== Diagnostic reports ===\n  launchservicesd CPU events: %d\n" \
  "$(ls /Library/Logs/DiagnosticReports/ 2>/dev/null | grep -c launchservicesd)"

echo
echo "=== Uptime ==="
uptime | awk '{print "  " $0}'

The script prints four blocks: daemon process state (RSS, etime), DB size and counts, recent CPU diagnostic-report count, and current uptime. All numbers are absolute — interpret them against the baseline thresholds below.

Interpreting the Snapshot

launchservicesd RSS

Daemon etime (elapsed time since launch)

launchservicesd is launched once per boot and lives until reboot. etime close to uptime is normal. etime significantly less than uptime means the daemon was relaunched mid-session — usually after a crash; check Diagnostic Reports.

DB size

Bundle / claim / record counts

There is no absolute threshold — these matter relative to the expected number of installed apps. Useful sanity check:

ls /Applications /Applications/Utilities ~/Applications 2>/dev/null | wc -l

If bundle id: count is 5x or more above the visible-.app count, the DB has stale records.

Diagnostic-report CPU events

/Library/Logs/DiagnosticReports/launchservicesd-*.cpu_resource.diag files indicate the daemon hit a CPU threshold (typically 80% sustained for 90s). Each file is one event. Recent volume:

find /Library/Logs/DiagnosticReports -name 'launchservicesd*.cpu_resource.diag' -mtime -7 | wc -l

Rebuild Procedure

Rebuild only when the snapshot shows multiple red flags. The rebuild takes 1–10 minutes depending on app count.

# Rebuild the LaunchServices database
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister \
  -kill -r -domain local -domain system -domain user

What the flags do:

Side effects:

• "Open With" submenus regenerate (a few seconds of "no apps available")
• Default-app preferences are preserved (stored separately)
• The Dock badge and icon caches are NOT affected
• A new launchservicesd process is spawned; PID changes

After rebuild

Re-run ls-stats to confirm RSS, DB size, and counts dropped.

Common Patterns

Snapshot before/after a rebuild

ls-stats > /tmp/ls-before.txt
"$LSREG" -kill -r -domain local -domain system -domain user
ls-stats > /tmp/ls-after.txt
diff -u /tmp/ls-before.txt /tmp/ls-after.txt

Track DB growth across boots

Append a snapshot to a logbook on each session:

{ date -Iseconds; ls-stats; echo "---"; } >> ~/.local/state/launchservices.log

Plot or grep over time to see whether DB size is monotonically growing.

Identify the registrar driving CPU

When launchservicesd is hot and you suspect a specific app:

log stream --predicate 'process == "launchservicesd"' --style syslog | head -200

Look for repeated bundle id or path strings — that's the offender.

Check for bottle-creation amplification

Wine/CrossOver bottle creation registers hundreds of .exe-as-bundle entries. Count them:

"$LSREG" -dump 2>/dev/null | grep -c -i 'wineprefix\|bottle'

A 4-digit answer is the smoking gun.

Justfile Recipe

[doc('Quantify LaunchServices DB and launchservicesd state (macOS)')]
[macos]
ls-stats:
    @~/.local/bin/ls-stats

The [macos] attribute (just 1.34+) skips the recipe on non-Darwin. On older just versions, drop the attribute and let the script's uname -s check do the gating.

Agentic Optimizations

Quick Reference

Key paths

Useful flags

Indicator thresholds (rough)

Error Handling

Related Skills

• macos-incident-postmortem — when LaunchServices CPU caused a GUI hang, parse Diagnostic Reports there
• kitty-session-persistence — recover terminal sessions lost when WindowServer wedged on an LS XPC call