SETUP / FIRST LAUNCH

GET STARTED
WITH TIME.MD.

Install the macOS app, finish onboarding, unlock the local collectors with a trial or license, grant the permissions macOS requires, and confirm your first screen-time records are being written locally.

Requirements

time.md is a macOS desktop app for local screen-time analytics. It is designed for people who want detailed usage data without a cloud account or uploaded activity history.

MACOS

macOS 14+

time.md targets macOS 14 Sonoma or newer. If you build from source, use Xcode 15 or newer.

ACCESS

Full Disk Access

Required so the app can read local macOS and browser history files that Apple protects behind Privacy & Security.

NETWORK

Trial or license check

Internet is needed to start/verify the 14-day card-backed trial or activate a paid license. Your activity data is not sent.

Local-first by default

Screen time sessions, browser history views, exports, category mappings, blocking state, and optional input-tracking data are stored on your Mac. Trial/license requests send entitlement fields only.

Download and install

  1. Download the macOS app

    Use the Download button on the time.md website or the GitHub release linked from the site. The download is free; the app asks for a trial or license after onboarding.

  2. Move time.md to Applications

    Drag time.md.app into /Applications. This helps macOS permissions stay attached to the same app path after updates.

  3. Open it once

    Double-click the app. If macOS asks whether you want to open an app downloaded from the internet, choose Open.

If you run a development build from Xcode, grant permissions to the built app you are actually launching. Permissions granted to a different copy do not always transfer.

Onboarding, trial, and activation

On first launch, time.md shows a short onboarding tour before collectors start. The tour explains the main screens, local-only privacy model, optional website-blocking helper, and optional input tracking.

14-day trial

After onboarding, click Start 14-Day Free Trial. time.md opens Stripe Checkout in your browser to collect and store a card for the trial. The app never sees your full card number.

When Stripe finishes, the browser returns with a timemd://activate-trial deep link containing a Stripe Checkout session ID. time.md verifies that session, receives a trial token, and stores it locally in Keychain.

Paid license

If you bought the one-time desktop license, paste the TMD-... activation key from the checkout page or license email. A successful paid activation is cached locally so the app can continue working if a later verification attempt is offline.

Flow What time.md sends What stays local
Start trial Source label and request for a Stripe Checkout URL. Screen time, browser history, exports, categories, input data.
Verify trial Trial token or Checkout session ID, app version, random local device ID. Every activity row and every export file.
Activate license Activation key, app version, random local device ID. Raw usage database and all optional local databases.

Grant Full Disk Access

Full Disk Access lets time.md read local system and browser files that macOS protects. Without it, the app can launch, but historical Screen Time and browser history may be empty or incomplete.

  1. Open System Settings

    Go to System Settings → Privacy & Security → Full Disk Access.

  2. Add time.md

    Click the add button, choose /Applications/time.md.app, and enable the switch. If you see multiple copies, remove stale entries and add the copy you actually open.

  3. Restart time.md

    Quit and reopen the app. macOS applies this permission to new file reads after the app relaunches.

For optional permissions such as Input Monitoring, Accessibility, or the website-blocking helper, see the Permissions guide.

When data appears

After the trial or license unlocks the app, time.md starts local services. New app-usage sessions are recorded from frontmost-app changes while the app is running. A session is written after you switch away from an app, the screen sleeps, the session ends, or the app quits; very short fly-throughs under about two seconds are ignored.

Empty at first can be normal

If you just unlocked the app, use your Mac for a few minutes and switch between apps. The current app is not finalized into the database until the session ends.

Dashboard data

Overview, Review, Details, Calendar, Trends, Projects, and Reports read from screentime.db. Confirm your date filter includes the period you want.

Web History data

Web History reads local Safari, Chrome, Firefox, Arc, Brave, and Edge history databases when those browsers are installed and enabled in Settings → Web Browsers.

Refresh and sync behavior

time.md updates local data without uploading it. The app refreshes views after recorded sessions, on launch, on day changes, and when you return to the current period. Auto-saved files refresh on launch, after recorded sessions, at day changes, and periodically while the app is running. Browser history databases are prefetched in the background so the Web History screen can load quickly.

  • Use the date controls to return to Today if a past range is selected.
  • Reopen the app after granting Full Disk Access or Input Monitoring.
  • Use any visible Refresh button on screens such as Blocking or Web History when testing a change.
  • For scripts, install the CLI and query the local database directly.
timemd today --limit 5
timemd top-apps --since 7d --limit 20
timemd sql 'SELECT COUNT(*) AS rows FROM usage'

Local storage locations

These files are on your Mac. Deleting them removes local time.md history or settings, so export first if you want a copy.

Path Purpose
~/Library/Application Support/time.md/screentime.db Canonical SQLite usage history for app sessions and analytics.
~/Library/Application Support/time.md/screen-time-snapshot.json Readable JSON mirror for local scripts and automation.
screen-time-auto.<ext> in your export folder Auto-refreshed formatted export using your last selected format, sections, and relative date range.
~/Library/Application Support/time.md/web-history.db Opt-in local web history archive, separate from browsers' own history files.
~/Library/Application Support/time.md/input-tracking.db Optional keystroke/cursor events and aggregates when Input Tracking is enabled.
~/Library/Application Support/time.md/blocking-rules.db Website/app blocking rules, states, and audit events.
~/Library/Application Support/time.md/category-mappings.db Custom app-to-category mappings for Projects, Rules, Reports, and filters.
macOS Keychain and UserDefaults Trial token, activation key, entitlement preview, and app preferences.

Next steps

01

Understand permissions

Plain-English explanations for every macOS permission and network call time.md uses.

 02

Fix setup issues

Empty data, browser history, activation links, export writes, hidden app modes, and CLI/MCP setup.

 03

Read the FAQ

Privacy, telemetry, payments, offline use, browsers, permissions, accuracy, exports, blocking, and input tracking.
NEXT: PERMISSIONS DOWNLOAD TIME.MD