SUPPORT / RECOVERY

FIX TIME.MD
WITHOUT GUESSING.

Use these checklists when a view is empty, browser history is missing, permissions do not stick, activation gets stuck, exports cannot write, the app is hidden, blocking needs repair, input tracking is quiet, or CLI/MCP setup fails.

Five-minute quick check

Most setup issues are permission, date-range, or activation problems. Run this list first.

  1. Confirm unlock state

    Open Settings → License & Trial. You should see an active trial, paid activation, or a message explaining what failed.

  2. Return to Today

    If you are viewing a past day, week, or month, the current period will not automatically replace it until you return to the present range.

  3. Grant permissions, then restart

    Full Disk Access, Input Monitoring, and Accessibility changes usually require quitting and reopening time.md.

  4. Create a real session

    Use one app for more than a few seconds, switch to another app, then wait for the dashboard to refresh.

  5. Capture the exact error

    If a screen shows an error, copy the exact wording. It usually names the blocked file, database, or activation endpoint.

Overview, Review, Details, or Reports show no data

New installs need a completed session

time.md writes a session after you leave an app or the screen sleeps. The current app is still in progress and may not appear until the session finalizes.

What to check

  • The trial or license is active; collectors do not run while the app is locked.
  • The date range includes today or the period you expect.
  • You used an app for longer than about two seconds before switching away.
  • Full Disk Access is granted if you expect historical local Screen Time data.
  • The app was running while you expected live sessions to be recorded.

Try this

  1. Quit and reopen time.md.
  2. Open Safari for 20 seconds.
  3. Switch to Finder or another app for 20 seconds.
  4. Return to time.md and check Overview.
  5. If still empty, check the local database path below.
~/Library/Application Support/time.md/screentime.db
~/Library/Application Support/time.md/screen-time-snapshot.json

If those files do not exist after activation and app switching, the app may not have permission to write to Application Support or may be running from a damaged install. Move it to /Applications and reinstall the latest build.

Web History is missing browser data

Web History reads local browser databases. Private browsing/incognito windows, cleared history, uninstalled browsers, unsupported profiles, and missing Full Disk Access can all result in empty rows.

Symptom Likely cause Fix
No browsers listed time.md cannot see browser history files. Grant Full Disk Access, restart time.md, and confirm the browsers are installed.
One browser missing Browser disabled in Settings or using a profile time.md does not discover. Open Settings → Web Browsers and enable the browser. For Firefox, use a standard profile if possible.
Recent visits missing Browser has not flushed history yet, history was cleared, or visits happened in private mode. Close/reopen the browser, refresh Web History, and avoid private windows for test visits.
Older visits disappeared The browser deleted its own history. Enable Settings → Web Browsers → Persist web history locally before future clears.
Permission denied error macOS denied access to the browser database path. Re-add the exact app copy under Full Disk Access and restart.
Supported browsers

Safari, Chrome, Firefox, Arc, Brave, and Edge are supported. Chromium forks with custom profile paths may not appear automatically.

Full Disk Access still does not work

  1. Remove stale entries

    In System Settings → Privacy & Security → Full Disk Access, remove old time.md entries. macOS may keep entries for deleted copies.

  2. Add the real app path

    Add /Applications/time.md.app. If you run from Xcode, add the built app or Xcode depending on your launch method.

  3. Restart the app

    Quit time.md completely and reopen it. If it runs in the menu bar, use the menu bar item or Activity Monitor to ensure it actually quit.

  4. Restart macOS if needed

    Rarely, the macOS privacy database lags behind. A restart usually clears the stale permission state.

If a specific path appears in an error, include it when contacting support. It tells us whether the failure is Screen Time, Safari, Chrome, Firefox, or the local time.md database.

Trial deep link, checkout, or activation key problems

Trial did not reopen the app

Return to time.md manually. If the checkout success page shows a trial key, paste it into the activation screen. The automatic link should look like timemd://activate-trial?session_id=cs_....

Activation key rejected

Make sure you pasted the whole TMD-XXXX-... key, not the Stripe receipt number. Remove extra spaces and try again.

Trial says expired

Expired trials return an expired status from the entitlement API. Buy a license and paste the paid activation key to continue.

Cannot reach server

Check your internet connection, VPN, firewall, and system time. Saved paid activations and still-active saved trials can continue when temporary verification fails.

Reset only if you need to re-enter credentials

Settings → License & Trial → Reset removes saved trial/license state from this Mac. The app locks until you start a trial or paste a valid key again.

For license email reissues or purchase help, email [email protected] with the email used at checkout and any Stripe Checkout Session ID you have.

Export destination write failures

time.md stores a security-scoped bookmark for user-selected export directories. If the folder moves, is deleted, is on a disconnected drive, or macOS marks the bookmark stale, writing can fail.

  1. Choose the folder again

    Open the Export screen and reselect the destination folder. This refreshes the sandbox bookmark.

  2. Try a local folder

    Use ~/Downloads/time.md Exports to rule out iCloud, Dropbox, external drives, network volumes, or read-only folders.

  3. Check the filename

    Use a simple filename without slashes or path traversal. The export writer rejects unsafe absolute or parent-directory paths.

  4. Confirm disk access

    Make sure the folder exists and your user account can write to it. If not, choose a different folder.

Auto-export location

The live file is named screen-time-auto.<ext> in your selected export directory and mirrors your last selected format, sections, and relative date range.

The app disappeared from the Dock or menu bar

Settings → Visibility can show time.md in the Dock, menu bar, both, or neither. macOS ties the Dock icon and Cmd-Tab entry together; menu bar visibility is separate.

Mode Where it appears How to recover
Dock + Menu Bar Dock, Cmd-Tab, and menu bar. Normal mode.
Menu Bar Only Menu bar item, hidden from Dock/Cmd-Tab. Click the menu bar item, or reopen time.md from Spotlight/Finder.
Dock Only Dock and Cmd-Tab, no menu bar item. Use Dock, Cmd-Tab, Spotlight, or Finder.
Hidden No Dock icon and no menu bar item. Open /Applications/time.md.app from Finder or Spotlight to show the main window.

Website or app blocking needs recovery

Blocking is intentionally simple: On means blocked, Off means viewable. Website blocks use the optional helper; app blocks observe frontmost applications and hide or notify.

WEBSITE

Helper not installed

If a website block is on and the helper card says setup is needed, click Set up helper once. macOS asks for an administrator password.

UPGRADE

Version mismatch

Click Upgrade helper. Helper upgrades require admin approval because the helper lives in privileged system locations.

STUCK

Site still blocked

Turn the rule off, click Refresh, then use Turn off all blocks if needed. Run diagnostics to reconcile managed domain rules.

APP

Blocked app keeps hiding

Open time.md, go to Blocking, and switch the app rule off or delete it. Protected system apps are skipped unless you explicitly allow self/protected blocking.

SAFETY

Remove managed blocks

Use Turn off all blocks before uninstalling or deleting app data so time.md can clear helper-owned domain state.

SUPPORT

Still stuck?

Email support with the diagnostics message and whether the issue is a website domain, app bundle ID, or category rule.

Input data is not appearing

Input Tracking is optional and off by default. It only runs while time.md is running, after you enable it, and after macOS grants the required permission.

Check Why it matters
Settings → Input Tracking is on The master toggle must be enabled before any events are captured.
Keystroke/cursor level is not Off Each stream can be disabled independently.
Input Monitoring is granted macOS blocks global keyboard/mouse event taps without it.
Accessibility is granted if needed Some macOS configurations require Accessibility for global event access.
Capture is not paused ⌥⌘P pauses capture for 30 minutes.
Active app is not excluded Password managers such as 1Password and Bitwarden are excluded by default.
Secure Input is not redacting content macOS Secure Input can remove typed characters from stored rows.

If time.md does not appear under Input Monitoring, toggle Input Tracking on once, quit and reopen time.md, then check System Settings again.

CLI or MCP setup is not working

timemd command not found

Open Settings → CLI Access → Install. If Terminal still cannot find it, add ~/.local/bin to your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

CLI conflict or missing binary

If Settings reports a conflict, another file exists at ~/.local/bin/timemd. Rename or remove that file, then click Repair. If the bundled binary is missing, reinstall time.md.

MCP agent not seeing tools

Open Settings → MCP Integration. Confirm the server is on, the agent is registered, and the tools you need are not disabled. Restart the agent after changing config.

Manual MCP config

For agents time.md does not auto-install, copy the manual JSON snippet from Settings. The command path must point to the bundled timemd-mcp binary inside your installed app.

timemd help
timemd list-tools
timemd today --limit 5
CLI and MCP read local data

These tools query your local time.md databases. Be careful which terminal sessions, scripts, or AI agents you allow to use them.

When to contact support

Email [email protected] if the troubleshooting steps do not fix the issue.

  • Include your macOS version and time.md version.
  • Say whether you are using a trial or paid activation.
  • Paste the exact error message and file path, if shown.
  • For browser issues, name the browser and profile if known.
  • For blocking issues, name the domain/app and the diagnostics summary.
NEXT: FAQ EMAIL SUPPORT