launchservices-health

LaunchServices Health (macOS)

When to Use This Skill

Use this skill when...	Use something else when...
launchservicesd is at sustained high CPU	General process forensics — use ps/top directly
GUI feels sluggish after weeks of uptime	The machine actually hung — see macos-incident-postmortem
Quantifying LS DB bloat (size, bundle count, claim count)	Checking app launch failures — use system_profiler SPApplicationsDataType
Deciding whether lsregister rebuild is warranted	First-time install setup — use configure-plugin

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

Path	Purpose
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister	The lsregister CLI — not on $PATH, must be invoked by absolute path
~/Library/Application Support/com.apple.PersistentURLTranslator/	Per-user persisted state
/var/folders/*/0/com.apple.LaunchServices*	LS cache directories (varies by macOS version)

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

RSS (KB)	Meaning
< 50 000 (~50 MB)	Healthy
50 000 – 150 000	Normal for active use
150 000 – 400 000	Bloated; consider rebuild
> 400 000 (~400 MB)	Pathological; rebuild warranted

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

Size	Meaning
< 5 MB	Normal
5 – 20 MB	Healthy heavy-app workstation
20 – 50 MB	Bloated; rebuild improves things
> 50 MB	Pathological

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

Count (last 7 days)	Meaning
0	Normal
1 – 3	Notable; monitor
4+	Pattern; likely a misbehaving registrar — investigate

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:

Flag	Effect
-kill	Reset the existing database first
-r	Recursively scan for bundles to register
-domain local	/Applications
-domain system	/System/Applications, /System/Library
-domain user	~/Applications, ~/Library/Application Support

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

Context	Command
One-line size	$LSREG -dump 2>/dev/null | wc -c | awk '{printf "%.1f MB\n", $1/1048576}'
RSS only	ps -o rss= -p "$(pgrep -x launchservicesd)"
Bundle count	$LSREG -dump 2>/dev/null | grep -c '^bundle id:'
Recent CPU events	find /Library/Logs/DiagnosticReports -name 'launchservicesd*.cpu_resource.diag' -mtime -7 | wc -l
Daemon uptime vs system uptime	ps -o etime= -p "$(pgrep -x launchservicesd)"; uptime

Quick Reference

Key paths

Path	Purpose
/System/.../Support/lsregister	The CLI
/Library/Logs/DiagnosticReports/	CPU and crash diag files
~/Library/Application Support/com.apple.PersistentURLTranslator/	Per-user state

Useful flags

Flag	Description
-dump	Print the entire DB to stdout
-kill -r -domain ...	Rebuild
-h	List all flags (undocumented elsewhere)
-f <bundle>	Force-register a single bundle
-u <bundle>	Unregister a bundle

Indicator thresholds (rough)

Metric	Healthy	Bloated	Rebuild
DB size	< 5 MB	20–50 MB	> 50 MB
Daemon RSS	< 50 MB	150–400 MB	> 400 MB
Bundle count vs visible apps	1–2x	3–5x	> 5x
CPU diag events / 7 days	0	1–3	4+

Error Handling

Symptom	Cause	Fix
lsregister: command not found	Not on $PATH by design	Use the full /System/.../Support/lsregister path
lsregister -dump exits non-zero with stderr	Permissions or DB corruption	Capture stderr separately; rebuild may resolve it
pgrep -x launchservicesd returns nothing	Daemon crashed and not yet relaunched	Check Diagnostic Reports; force a relaunch with lsregister -kill -r ...
Rebuild appears to hang	Indexing many app bundles is genuinely slow	Wait — typical 1–10 min depending on app count
Sudden RSS jump after Homebrew upgrade	Many bundles re-registered at once	Expected; will settle within minutes

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