{"id":47398420,"url":"https://github.com/ActivityWatch/aw-import-screentime","last_synced_at":"2026-04-03T12:01:23.363Z","repository":{"id":52692675,"uuid":"357474788","full_name":"ActivityWatch/aw-import-screentime","owner":"ActivityWatch","description":"Import data from Apple's Screen Time on macOS and iOS to ActivityWatch","archived":false,"fork":false,"pushed_at":"2023-02-24T20:14:28.000Z","size":36,"stargazers_count":43,"open_issues_count":5,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-18T23:54:20.924Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ActivityWatch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null},"funding":{"github":["ActivityWatch"],"open_collective":"activitywatch","liberapay":"ActivityWatch","custom":["https://activitywatch.net/donate/"]}},"created_at":"2021-04-13T08:12:46.000Z","updated_at":"2025-10-09T16:19:07.000Z","dependencies_parsed_at":"2023-09-23T14:40:42.493Z","dependency_job_id":null,"html_url":"https://github.com/ActivityWatch/aw-import-screentime","commit_stats":{"total_commits":5,"total_committers":3,"mean_commits":"1.6666666666666667","dds":0.4,"last_synced_commit":"df9f8618780e4231aa4545f59df93124b983e415"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ActivityWatch/aw-import-screentime","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ActivityWatch%2Faw-import-screentime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ActivityWatch%2Faw-import-screentime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ActivityWatch%2Faw-import-screentime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ActivityWatch%2Faw-import-screentime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ActivityWatch","download_url":"https://codeload.github.com/ActivityWatch/aw-import-screentime/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ActivityWatch%2Faw-import-screentime/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31349561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T08:03:20.796Z","status":"ssl_error","status_checked_at":"2026-04-03T08:00:37.834Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-20T09:00:29.479Z","updated_at":"2026-04-03T12:01:23.355Z","avatar_url":"https://github.com/ActivityWatch.png","language":"Python","funding_links":["https://github.com/sponsors/ActivityWatch","https://opencollective.com/activitywatch","https://liberapay.com/ActivityWatch","https://activitywatch.net/donate/"],"categories":["Other Watchers :gear:"],"sub_categories":[],"readme":"# aw-import-screentime\n\nImport Apple's Screen Time App.InFocus telemetry (stored in Biome `SEGB` files) into [ActivityWatch](https://activitywatch.net) buckets. All CLI commands emit JSON to stdout so you can easily pipe the results into `jq`, persist them, or feed them to other tools.\n\n## What you get\n\n- Enumerate Screen Time devices by reading `~/Library/Biome/sync/sync.db`.\n- Decode `App.InFocus` [SEGB files](https://blog.d204n6.com/2022/09/ios-16-breaking-down-biomes-part-4.html) into stitched ActivityWatch events.\n- Preview stitched timelines before importing anything.\n- Push events directly into an ActivityWatch server (testing or production) with per-device buckets.\n- Inspect raw protobuf fields for debugging.\n\n## Requirements\n\n- macOS with Screen Time enabled (the tool reads from `~/Library/Biome/streams/restricted/App.InFocus/remote/…`).\n- Full Disk Access for the terminal/IDE you use to run the CLI.\n- Python 3.10–3.13 and [uv](https://docs.astral.sh/uv).\n- An ActivityWatch server (default port 5600, testing port 5666).\n\n## Installation\n\n```bash\nuv sync\nsource .venv/bin/activate\naw-import-screentime --help\n```\n\n`uv sync` also installs `ccl-segb` from [GitHub](https://github.com/cclgroupltd/ccl-segb), which is required to parse the binary `SEGB` stream Apple stores on disk.\n\n## Access to Screen Time data\n\nApple stores the data this tool consumes under `~/Library/Biome`. Make sure your shell/IDE already has Full Disk Access so it can read:\n\n- `~/Library/Biome/sync/sync.db` (device metadata)\n- `~/Library/Biome/streams/restricted/App.InFocus/remote/\u003cdevice_id\u003e/*`\n\nIf the directories are empty, unlock Screen Time in System Settings, ensure “Share Across Devices” is enabled on both macOS and iOS, and wait for iCloud to sync the files locally.\n\n## CLI overview\n\n```bash\nUsage: aw-import-screentime [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n  --log-level [ERROR|WARNING|INFO|DEBUG]\n  --tz [local|utc]           Timestamp timezone for stitched events.\n  --config PATH              Reserved for future config support.\n  --version                  Print the CLI version and exit.\n  --help                     Show this message and exit.\n\nCommands:\n  devices\n  events\n  file\n```\n\nAll commands emit JSON structures; logs go to stderr via Rich. The `--since` option (available on `events` and `file`) accepts ISO-8601 timestamps or relative values such as `24h`, `7d`, `now-15m`, `yesterday`, or `today`.\n\n### `devices`\n\nList DevicePeer identifiers discovered in `sync.db`.\n\n```bash\naw-import-screentime devices --paths | jq .\n```\n\n- `--platform` lets you query a different Apple platform (default `2`, which is iOS).\n- `--paths` includes the resolved stream directory for each device.\n\n### `events preview`\n\nDry-run the stitching pipeline for one or more devices. This never contacts ActivityWatch; it is useful for inspecting what would be imported.\n\n```bash\naw-import-screentime events preview \\\n  --device ABCDEF0123456789 \\\n  --limit 10 \\\n  --since 24h \\\n  --storefront us --storefront se \\\n  | jq .\n```\n\n- `--limit` controls how many files per device are read (`0` = all).\n- `--since` clips the resulting intervals to recent activity.\n- `--storefront` controls the App Store locales used to enrich bundle titles (defaults to `[\"us\"]`).\n\n### `events import`\n\nRun the same decoding logic as `preview`, but stream the events into ActivityWatch. A bucket named `aw-import-screentime_ios_ios-\u003cdevice_id\u003e` is created per device (append `--bucket-suffix` if you want a custom suffix).\n\n```bash\n# Import the last 24h from every device into an ActivityWatch test server on port 5600\naw-import-screentime events import --since 24h --limit 20\n```\n\n- `--testing` switches the `ActivityWatchClient` into testing mode (port `5666`). Use this whenever you are talking to `aw-server --testing`.\n- `--port` overrides the ActivityWatch port explicitly, e.g. `--port 5666` if you prefer to spell it out.\n- `--bucket-suffix` appends a suffix to each bucket name (handy for experiments).\n- `--device`, `--limit`, `--since`, and `--storefront` mirror the `preview` command.\n\n### `file`\n\nInspect a single SEGB file either as raw protobuf entries or stitched intervals.\n\n```bash\n# Stitched summary (default)\naw-import-screentime file ~/Library/Biome/streams/restricted/App.InFocus/remote/00000000-0000-0000-0000-000000000000/00012345 --max-events 10 | jq .\n\n# Raw protobuf dump\naw-import-screentime file ... --raw --raw-limit 5 | jq .\n```\n\n- `--raw/--stitched` toggles the output mode.\n- `--raw-limit` caps how many protobuf entries are decoded.\n- `--max-events` limits how many stitched events are included in the JSON payload (set to `0` for everything).\n- `--since` and `--storefront` behave like the `events` commands.\n\n## Testing with ActivityWatch port 5666\n\nActivityWatch exposes a dedicated testing port (5666) when you launch `aw-server --testing`. Use one of the following when experimenting against that instance:\n\n- `aw-import-screentime events import --testing ...` (preferred; it switches both the ActivityWatch port and client label).\n- `aw-import-screentime events import --port 5666 ...` (if you want to specify the port manually).\n\nBoth options keep the production data on port 5600 untouched while you verify the importer.\n\n## Limitations\n\n- Only the App.InFocus stream is decoded today; other Screen Time streams (notifications, website usage, etc.) are ignored.\n- If Biome has not synced yet, the CLI simply reports empty devices.\n- macOS sometimes logs incomplete foreground durations; intervals are stitched best-effort and may be shorter than what you see in Screen Time.app.\n- App title enrichment depends on live App Store lookups and therefore needs network access the first time a bundle is seen.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FActivityWatch%2Faw-import-screentime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FActivityWatch%2Faw-import-screentime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FActivityWatch%2Faw-import-screentime/lists"}