What Blocking does
Blocking turns selected websites, apps, or categories into active interventions. A direct block stays active until you turn its switch off. Policy-driven cooldowns can also be created after repeated visits or app sessions, then expire after the configured cooldown window.
Website rules
Make domains unviewable system-wide with the helper installed.
App rules
Hide blocked apps when they become the frontmost app and show a countdown/reminder.
Category rules
Apply the same policy to groups such as Social, Games, or custom app categories.
Rule types and states
| Target | Example | How it is enforced |
|---|---|---|
| Website | reddit.com |
Network-level domain rules applied by the time.md helper when the rule is active. |
| App | Slack or a bundle identifier |
Frontmost-app observation hides or otherwise handles the app when opened. |
| Category | Social |
Policy evaluation matches the app’s category and applies the chosen intervention. |
The Blocking screen labels enabled direct blocks as BLOCKED and disabled blocks as VIEWABLE. Deleting a block removes the rule definition. Turning it off keeps the rule but makes the target viewable again.
Website blocking
Website blocks normalize domains before enforcement. A rule such as https://www.reddit.com/r/all is normalized to reddit.com. time.md then expands common variants because /etc/hosts cannot express true wildcards.
Domain normalization
Protocols, paths, query strings, leading www., and wildcard prefixes are stripped before the rule is stored.
Hostname variants
Rules include the base domain, www, and common subdomains such as old, new, m, mobile, i, amp, and np.
Observed variants
The policy path can carry observed hostnames so sites you actually visit can be added to managed enforcement state.
Website access events are derived from local browser history polling. If browser history access is unavailable, app analytics continue and website-policy events may be incomplete until permissions or browser access recover.
App and category blocks
App blocking runs through frontmost-app observation. When a blocked app opens, time.md shows a notice and, by default, hides the app so you can switch away. Internal enforcement modes also support notify-only and quit-request behavior.
- Finder, System Settings, Terminal, time.md, and other protected system paths are not hidden by default.
- Manual blocks stay active until you turn the rule off.
- Cooldown blocks show the remaining time and clear when the cooldown expires.
- Category blocks use time.md’s app category mappings, including automatically populated macOS category metadata where available.
Privileged website blocking helper
System-wide website enforcement needs a privileged helper because normal apps cannot safely edit /etc/hosts or manage pf anchor state. The helper is only needed when website blocks are on.
-
Set up once
When website blocks are active and the helper is missing, the app shows a Website Blocking Helper card. Choose Set up helper once; macOS asks for administrator approval.
-
Upgrade when requested
If the helper version is old, choose Upgrade helper. Admin approval is required for install or upgrade, not for every rule change.
-
Rule changes are staged locally
After setup, time.md publishes desired domain state under Application Support and the helper applies it without another password prompt.
| System resource | How time.md uses it |
|---|---|
/etc/hosts |
Maintains one marker-delimited block owned by time.md and preserves unrelated user content. |
/etc/pf.anchors/com.bontecou.time-md |
Owns a pf anchor for best-effort network rules when resolved IP addresses are available. Hosts entries remain the primary domain-name path. |
~/Library/Application Support/time.md/DomainBlockHelper |
Staging area for desired state, helper status, and apply results. |
Diagnostics and repair
The Blocking screen includes diagnostics that classify the system as healthy, degraded, or broken. Use diagnostics after installing the helper, after editing rules, or any time a site remains blocked after you expected it to clear.
Healthy
Helper status and active block state agree. Website blocks should apply and clear normally.
Degraded
A helper or recovery issue exists. Website blocks may need setup, upgrade, or repair.
Broken
time.md detected unsafe partial state, such as a malformed managed hosts block, that needs attention.
Repair operations clear expired cooldowns, reconcile active domain blocks, and recreate owned helper state without touching unrelated hosts, pf, VPN, or firewall rules.
Remove all managed blocks
If you need to immediately restore access, use the bulk recovery action in Blocking. The UI may label the button Turn off all blocks; internally the conservative recovery operation is Remove all managed blocks.
-
Clear active states
Active block timestamps are set to nil so apps and websites become viewable again.
-
Clear helper state
The helper removes the time.md-owned hosts marker block and clears the owned pf anchor state.
-
Leave rules intact
Your block rules remain in
blocking-rules.db. Turn them on again when you want to re-enable them.
For a full uninstall, remove managed blocks first, then uninstall the helper with admin consent.
Optional Chromium browser-extension bridge
time.md’s source includes an optional browser-extension bridge for Chromium-family browsers. Its purpose is a low-latency URL signal for blocking-policy evaluation. It is not required for normal screen-time analytics, app blocking, or browser-history polling.
- If the bridge is absent, website access can still be inferred from local browser history when permissions allow it.
- The bridge does not upload browsing data to time.md servers.
- Private/incognito behavior depends on browser extension permissions and the browser’s own history rules.
- Full Disk Access and Web History troubleshooting still apply to the polling path.