Screen Time Exporter v2.0.0
Install
The Grafana dashboard with demo data: today's screen time of 7.9 hours with an hourly sparkline, today per device, the 7-day average and its change, daily bars by device and by category, a category donut, and the top apps.

Apple Screen Time from iPhone, iPad and Mac

Your Screen Time,
in your own database.

Read on your Mac every 15 minutes, kept in local SQLite, sent to Grafana, Home Assistant, your terminal and your AI assistant.

then screentime setup

GitHub Docs

Free & open source · macOS · Python 3.11+ · MIT · v2.0.0

Read on the Mac, every 15 minutes

Your Mac already receives your iPhone and iPad usage through iCloud. Every 15 minutes screentime run reads Apple’s stores, saves new sessions to SQLite and passes changed days on.

  1. Devices

    • iPhone · iPadShare Across Devices
    • This Macits own usage

  2. Apple’s stores

    • BiomeApp.InFocus
    • knowledgeC.db/app/usage, via a copy

  3. On your Mac

    • screentime runlaunchd, every 15 min
    • SQLitesessions, daily aggregates
    • App namesinstalled app · App Store

  4. Where it goes

    • InfluxDB → Grafanadashboard included
    • Home AssistantREST sensors
    • summary · dumpterminal, CSV, JSON
    • screentime mcpClaude · Codex · Cursor
  • Sessions, not totals. Every app session, rolled up per day, app, category and hour.
  • Idempotent exports. Changed days are rewritten, never duplicated. A failed export retries on the next run.
  • Readable names. 270+ apps built in, the rest named from the app on your Mac or the App Store.

A Grafana dashboard, ready to go

Overview, devices and categories, apps, night and rhythm, with filters for device, category and app. docker/docker-compose.yml starts InfluxDB 2.7 and Grafana 12 with the datasource and the dashboard provisioned; an existing Grafana imports screentime.json.

Devices and categories

Daily stacked bars per device and per category, the total per device and each category’s share.

The Category share panel with demo data: a donut chart led by Coding at 19.4 percent, Social at 18.2 percent and Media at 17.7 percent, with a legend of nine categories.

Apps

The top apps across all devices, an app table with sessions and average per active day, and the top ten per device.

The Top apps panel with demo data: horizontal bars led by VS Code at 37.1 hours, Chrome at 33.4 hours and YouTube at 22.6 hours.

Rhythm

A typical day as average minutes per hour, sessions per day, and a weekday by hour grid.

The Typical day panel with demo data: average minutes per hour from 00 to 23, stacked by MacBook, iPad and iPhone, busiest in the afternoon and around 21:00.

After midnight,
counted apart.

Use after midnight is counted on its own: in the dashboard, in Home Assistant, in every report and over MCP.

  • Late night00:00 – 06:00
  • Deep night03:00 – 06:00
  • Bedtime and wake-uplast and first use

Sessions crossing a boundary are split, and a night counts towards the day it falls on. Bedtime and wake-up frame the night’s longest gap of at least three hours without use on any device.

The Night section of the dashboard with demo data: 8 minutes of late night today, 157 minutes over 7 days, no deep night, a bar chart of late night per day split into 00–03 and 03–06, and a bedtime and wake-up chart with the phone-free night shaded between the lines.

Sensors for
Home Assistant.

Sensors per device, per night and per week, updated every 15 minutes. No integration needed.

Sensors and automations
A terminal running screentime summary --week last on demo data: 64 hours 15 minutes in total, minus 15 percent against the week before, bars for devices, days, top apps and categories, the late-night line and an hour-of-day sparkline.

A week in
the terminal.

screentime summary reports a week, a day or any range: total, change against the period before, devices, days, top apps, categories, late night and an hour-of-day sparkline.

  • summary --week lasttext
  • summary --day --format markdownfor notes
  • summary --format jsonfor scripts
  • dump --daily -o days.csvCSV or JSON

Both read the database read-only, so they never get in the way of the next sync.

Ask your
assistant.

screentime mcp lets Claude, Codex or Cursor answer questions from your local data, read-only.

Needs the [mcp] extra. Claude Desktop, Codex and Cursor: docs/mcp.md. Or let an agent do the whole setup: the prompt.

Was I on screens after midnight last week? Which night was the worst?

get_late_night last_week

Yes, every night. 3 h 09 min after midnight in total, 29 min of it after 03:00.

The worst was Sunday into Monday: 1 h 01 min, the only night past 03:00. Friday into Saturday came close with 52 min.

  • Mon
  • Tue
  • Wed
  • Thu
  • Fri
  • Sat
  • Sun

Demo data

Set up in three steps

You need a Mac signed in to the same Apple Account as your iPhone and iPad, with Screen Time → Share Across Devices on for every device, and uv, which brings its own Python 3.11+.

  1. Install

    One package, one command, from GitHub.

  2. Run the wizard

    Finds and names your devices, tests InfluxDB and Home Assistant, writes the config, runs a first sync and installs the agent.

  3. Grant Full Disk Access

    Apple’s stores are protected. Allow your terminal, and the Python interpreter that setup prints for the background agent, under Privacy & Security → Full Disk Access. screentime doctor checks the rest.

Setup guide Upgrading from v1 Let an AI agent install it

Privacy

Everything stays on your Mac unless you configure a sink. Unknown apps are named from the Mac first; only bundle ids it cannot name go to Apple’s public lookup API, and [lookup] enabled = false turns that off. What an assistant sends to its model is up to the assistant.

What Apple keeps

A few weeks; Biome holds about four. The first sync reads what is still there, and anything older exists only if the exporter was running. Read-only towards Apple: knowledgeC.db is read through a temporary copy.

macOS only

iPhone and iPad data reaches the exporter through a Mac with Screen Time sharing on; there is no iOS app. Tested on macOS 27 on Apple silicon. Not on PyPI yet: install from GitHub with uv, pipx or pip.

App names

270+ bundle ids ship with a name and one of 14 categories. Installed Mac apps name themselves; iPhone apps outside the App Store keep a guessed name until you name them in [apps] (how). More mappings are welcome in pull requests.

Upgrading from v1

v2 replaces the CSV, the .env file and aw-import-screentime with one installed tool, and the v1 Home Assistant entity ids stay. The steps are in docs/migration.md, the changes in the changelog.

Unofficial

An independent open-source hobby project, not affiliated with, endorsed or sponsored by Apple. Apple, Screen Time, iPhone, iPad, Mac, macOS and iCloud are trademarks of Apple Inc., used only to describe the data the project reads.