---
name: screentime
description: On-demand, read-only read of this Mac's local Screen Time data (the knowledgeC.db app-usage store). Use when the owner asks "screen time", "where did my time go", "how long was I on X", "what apps did I use most this week", "was yesterday focused", or "how late did I work". The owner asks in plain language — never make them run a command. The agent runs the reader as plumbing and answers with the story — headline hours vs the recent average, what dominated, the deep-work block, late-night flags — not a table dump. Read-only against the source; its only writes are its own committed history files. Records THIS Mac only (no iPhone/iPad data), runs locally, needs macOS Full Disk Access. NOT comms triage (that's attention-digest), NOT texts (that's imessage), NOT vault growth (that's vault-stats). Requires the screentime module.
served: false
---

# Screen Time — where did my time go (on-demand, read-only)

The owner asks in plain language; this skill reads the Mac's local Screen Time
store and hands back a **useful synthesis** — never a raw command for the owner
to run, and never a table dump unless they ask for one. The full procedure is
canonical in **[[Screen Time]]** (`Agent/docs/Screen Time.md`); this is the trigger.

## When this skill fires
The owner says, in chat, some form of *"screen time / where did my time go / how
long was I on X / what did I use most this week / was yesterday a focused day /
how late did I work last night."* On-demand and owner-only — never scheduled,
never sent anywhere.

## What to do
1. **Read [[Screen Time]]** (`Agent/docs/Screen Time.md`) — it wins over anything remembered here.
2. **Scope the ask, then run the reader as plumbing** —
   `"${ALEXANDRIA_PYTHON:-python3}" -m alexandria_vault.engine.screentime_read --vault . --json`
   Default to the last 7 logical days; scope with `--since today|yesterday|2w|30d|YYYY-MM-DD|all`
   when the owner names a window. The owner never sees or types this command. Each run also
   upserts the long-run trend series (`Agent/scripts/screentime/history.json`); query it with
   `--history` when the ask is a trend ("more than last week?").
3. **Sanity-check the coverage line before synthesizing.** Every run prints one stderr line —
   `window <start> → <end> · N day(s) with data · headline <metric> · /app/usage <status>`.
   A headline of `screen-on` means the OS stopped donating per-app data and totals are the
   **screen-on fallback** — say so, and don't invent an app breakdown. knowledgeC retains only
   **~4 weeks**: an unread stretch near that horizon is data about to age out — read it now and
   flag it.
4. **Answer with the story, not a table.** Lead with the headline (total hours, vs the recent
   average), then what dominated (apps / categories), the longest deep-work block, and anything
   notable — a late-night stretch, an unusually light or heavy day, a category shift. Offer
   drill-downs (per-day, per-app, hourly shape) instead of defaulting to them.

## Rules (detailed in [[Screen Time]])
- **Prerequisite: Full Disk Access.** macOS blocks `knowledgeC.db` until the app running the
  assistant (Claude, or its terminal) has Full Disk Access — the same one-time System Settings
  grant as the iMessage reader, not a credential.
- **This Mac only.** knowledgeC records the machine it lives on — no iPhone/iPad data syncs in,
  and another machine's copy shows that machine's usage. Run it where the owner actually works.
- **Read-only against the source** — the live DB is snapshot-copied, never opened; the only
  writes are the reader's own history files (meant to be committed).
- **Respect the semantics:** days end at the configured boundary (default **04:00** — a 1am
  session belongs to the evening's day); "sessions" are merged stretches, not app switches;
  unlock counts are a floor, not a count.
