Digital Wellbeing Docs
Digital Wellbeing is a free, open-source Windows desktop app that tracks your screen time, lets you enforce app limits, and gives you a clear picture of your habits — all without sending a single byte to the cloud.
This documentation covers every feature in depth, with real-world scenarios so you know exactly when and how to use each setting.
Installation
Digital Wellbeing ships as a standard Windows NSIS installer. No admin rights required for most features.
Digital-Wellbeing-Setup-x.x.x.exe.%APPDATA%\digital-wellbeing\wellbeing.db — a plain SQLite file you can inspect, export, or delete at any time.System requirements
| Requirement | Details |
|---|---|
| OS | Windows 10 or Windows 11 (x64) |
| RAM | ~50 MB at idle, ~80 MB during active use |
| Disk | < 150 MB installed; DB grows ~1 MB/month |
| Network | Only for update checks (every 4 hours). No telemetry. |
First Launch
On first launch, the app opens to the Dashboard and starts tracking immediately. No setup wizard, no account — it just works.
What happens in the background
Every 5 seconds (configurable), the app calls a Windows API (GetForegroundWindow) to find which app is currently active. It logs that to a local SQLite database. After 30 days of use, you'll have a rich picture of exactly how you spend your time.
System tray behavior
Closing the window does not quit the app — it minimizes to the system tray. This is intentional: tracking continues without keeping a window on screen. To fully exit, right-click the tray icon → Quit.
Double-click the tray icon to reopen the dashboard at any time.
Dashboard
The Dashboard is the home screen. It shows a real-time view of today's usage plus analytics from your full history.
Metrics row
| Card | What it means |
|---|---|
| Today | Total tracked screen time today, plus a ±delta vs the same day last week. |
| Weekly avg | Average daily screen time this week, with last week's daily average shown below for comparison. |
| Limit alerts | How many app limits fired today. Shown in red if non-zero — open App Limits to see which ones triggered. |
Hourly breakdown chart
A 24-bar chart showing how much time you used apps in each hour of today. Useful for spotting patterns like "I'm always distracted between 2–4 PM."
Top apps
The top 5 apps by usage today, with a proportional bar showing each app's share of your total screen time.
App trends
Each tracked app shows an arrow ↑ or ↓ with a percentage, comparing today's usage to your 7-day average. Useful for catching drift — "I used Twitter 60% more this week."
Usage calendar (365-day heatmap)
A full year of squares, color-coded by usage vs your daily goal:
- ■ Green — under your daily goal (good)
- ■ Red — over your daily goal
- ■ Empty — no data (app wasn't running)
Longest focus block
The longest uninterrupted stretch of time you spent on a single app today. If you were in VS Code from 9:00 to 10:45 AM without switching, that's a 1h 45m focus block.
Week comparison
Compares this week's total screen time to last week's. Shows the delta in hours and whether you're trending up or down.
App Limits
App Limits lets you set a daily time budget for any app. When you hit the limit, the app can notify you (soft) or close itself (hard) — your choice.
Setting a limit
Soft vs Hard limits
| Mode | What happens at 100% | Best for |
|---|---|---|
| Soft 🔕 | A notification fires. The app stays open. You decide what to do. | Work tools you legitimately need; apps you want awareness about. |
| Hard 🔔 | App is force-closed via PowerShell. Cannot be bypassed without removing the limit. | Social media, games, streaming apps — things you want to genuinely stop. |
Warning thresholds
Four warning points fire before the limit is hit:
| Threshold | Behavior | Configurable |
|---|---|---|
| 50% | Optional early heads-up — "halfway there" | On/Off in Settings |
| 80% (default) | Primary warning — "getting close" | Changeable to 50/70/80/90% |
| 95% | Final warning — "5% left" | On/Off in Settings |
| 100% | Limit reached — enforce soft or hard mode | Always fires |
Grace period
Only applies to hard limits. When the limit is hit, instead of closing immediately, the app waits the grace period duration, then shows a final notification before closing. Options: 0 (close immediately), 5, 10, or 15 minutes.
Snooze
When a hard limit fires, the notification dialog offers a Snooze button. Snoozed apps get a 15-minute override — the limit is temporarily suspended and the app stays open. After 15 minutes, the limit enforces again.
App Usage
The App Usage tab shows a detailed table of every app tracked today — time spent, number of times opened, and category.
Columns
| Column | Description |
|---|---|
| App | App name with icon (if resolvable) and a proportional usage bar underneath. |
| Category | Auto-detected category. Click the pill to override it manually. |
| Time | Total tracked seconds today, displayed as Xh Ym. |
| Opens | How many times you switched to this app today (foreground focus count). |
Changing a category
Click any category pill — a dropdown appears with all 9 categories. Select one. The change is saved immediately and persists across restarts. Once you manually set a category, the auto-classifier won't override it.
Sorting
Click any column header to sort. Click again to reverse sort direction. The sort arrow shows the active column. Default sort is by Time (descending) — highest usage app at the top.
Weekly Report
The Weekly Report gives you a broader view of your habits across the past 7 days.
7-day bar chart
Each bar represents total screen time for that day. The bars help you visually identify heavy days (usually weekdays) vs light days (weekends, or days you were productive offline).
Top apps this week
Your most-used apps ranked by total time across the 7-day window. Useful to compare against your daily top apps — sometimes an app you barely notice daily accumulates significant weekly hours.
App consistency grid
A 7-square grid per app showing which days that app was active (filled square) vs absent (empty square). Helps identify patterns like "I use Slack every weekday but never on weekends" or "I somehow opened TikTok 6 of the last 7 days."
Category breakdown
A summary of how time was distributed across categories this week (Browser, Development, Entertainment, etc.) — the same data as Dashboard but aggregated over 7 days.
Settings
Settings is split into four sections: Tracking, Notifications & Limits, Data, and About.
Tracking
| Setting | Options | Effect |
|---|---|---|
| Poll interval | 3s / 5s / 10s / 30s | How often the active window is sampled. Lower = more accurate data, slightly higher CPU. 5s is the sweet spot. Use 10–30s on battery. |
| Daily screen time goal | 3h – 10h | Sets the target for the heatmap calendar. Days under this goal show green. Doesn't enforce a limit — purely for visual tracking. |
| Launch at startup | On / Off | Registers or removes a Windows startup entry. When On, the app launches minimized to tray on every login. |
Notifications & Limits
| Setting | Effect |
|---|---|
| Enable notifications | Master toggle. Off = no alerts fire regardless of limit settings. |
| Primary warning threshold | The main alert percentage — fires when usage reaches 50/70/80/90% of the daily limit. |
| 50% warning | Optional early warning at the halfway mark. Good for apps with short limits (e.g., 30-min limit — get warned at 15 min). |
| 95% warning | Final warning when only 5% remains. Especially useful for hard limits so you have time to wrap up. |
| Grace period | Delay before a hard limit closes the app. 0 = immediate. 5/10/15 min = save-work buffer. Applies to all hard limits globally. |
Data
| Setting | Effect |
|---|---|
| Data retention | Auto-deletes usage records older than 7/30/90/365 days. Default 90 days. Lower = smaller DB, less historical data. |
| Export CSV | Downloads last 30 days of usage as digital-wellbeing-YYYY-MM-DD.csv to your Downloads folder. Columns: app_name, date, duration_seconds. |
About
Shows the current version, a link to Buy Me a Coffee if you'd like to support development, and a direct link to report bugs on GitHub Issues.
Categories
Every tracked app is assigned a category automatically using a built-in classifier with 200+ known apps. You can override any category from the App Usage tab.
App Usage categories (9 options)
| Category | Example apps |
|---|---|
| Browser | Chrome, Edge, Firefox, Brave, Opera, Vivaldi |
| Development | VS Code, IntelliJ, Terminal, Figma, Postman, Claude, GitHub Desktop |
| Communication | Slack, Discord, Teams, Zoom, WhatsApp, Telegram, Signal |
| Productivity | Notion, Obsidian, Word, Excel, Todoist, Acrobat |
| Entertainment | Spotify, VLC, Netflix, YouTube, OBS, Twitch, Plex |
| Gaming | Steam, Epic Games, Valorant, Minecraft, League of Legends |
| Social | Instagram, Twitter/X, TikTok, Reddit, LinkedIn |
| Utility | File Explorer, Task Manager, 7-Zip, VirtualBox, ShareX |
| Other | Anything the classifier doesn't recognize |
App Limits categories (5 options)
When creating a limit in App Limits, you pick from a simpler set: Work, Social, Entertainment, Utility, Other. These feed the productivity breakdown alongside the is_productive flag per limit.
How classification works
The classifier uses two strategies in order:
- Exact match — looks up the app name directly in a 200+ entry table
- Substring match — checks if the name contains keywords like "chrome", "slack", "studio", etc.
If both fail, the app is filed under "Other". You can always correct it via the category dropdown in App Usage.
User overrides persist
When you manually change a category, it's saved to the database with a user_overridden = 1 flag. The classifier never overwrites a user-set category, even across app restarts or updates.
Notifications
Notifications are Windows system notifications triggered by the Electron main process — they appear in the bottom-right corner and in the Windows notification center.
Notification types
| Trigger | Message example |
|---|---|
| 50% warning (optional) | "YouTube — 50% of daily limit reached (30 min used)" |
| Primary warning (80% default) | "Chrome — 80% of daily limit reached (48 min used)" |
| 95% warning (optional) | "Twitter — 95% of limit reached. 3 minutes left." |
| Hard limit hit | Dialog box: "YouTube limit reached. Got it / Snooze / Edit Limits" |
Notification reset
All notification flags reset at midnight every day. So if you get a 95% warning on Monday, you'll get it again on Tuesday once you hit 95% again — the app doesn't remember "I already warned you" across days.
Privacy & Data
Digital Wellbeing is designed to be completely private. No account, no cloud, no analytics.
What data is stored
| Data | Where | What's recorded |
|---|---|---|
| Usage logs | %APPDATA%\digital-wellbeing\wellbeing.db | app_name, date, timestamp, duration_seconds. No window titles. No URLs. No keystrokes. |
| App limits | Same SQLite DB | Limit config per app. Stored locally. |
| Settings | Same SQLite DB | Your preferences. No identifiers. |
| Update checks | GitHub API | Fetches latest release version number. No device ID sent. |
What is never collected
- Window titles or browser URLs
- Keystrokes or clipboard content
- Screenshots or screen recordings
- Any personally identifiable information
- Usage patterns sent to a server
Deleting your data
Delete %APPDATA%\digital-wellbeing\ to remove everything — database, settings, and all history. The app will create a fresh DB on next launch.
CSV export
Settings → Data → Export CSV downloads the last 30 days as a CSV file to your Downloads folder. You can import this into Excel, Google Sheets, or any analytics tool to run your own analysis.
FAQ
1Does this work on macOS or Linux?▾
Windows-only. macOS and Linux have placeholder stubs but active development and testing is Windows 10/11 only. macOS/Linux tracking will not work correctly.
2Can I use this on multiple PCs?▾
Each install tracks independently — there's no sync. Export CSV from each machine and combine them manually if you want unified data.
3Will the app slow down my PC?▾
No. The tracker uses a lightweight Windows API call every 5 seconds. Memory footprint is ~50–80 MB. CPU impact is negligible. On battery-constrained devices, set the poll interval to 10 or 30 seconds in Settings → Tracking.
4Hard limit isn't closing the app — what's wrong?▾
Check that the bell icon on the limit card is 🔔 (not 🔕 which is soft mode). The target app must also be running as a visible foreground process. Some protected UWP apps (Microsoft Store apps) may resist force-kill due to Windows app sandboxing.
5Can I track time on multiple monitors?▾
The tracker records whichever window is currently receiving keyboard/mouse focus (the foreground window). Secondary monitor windows that are visible but not focused are not tracked — this is a Windows API limitation.
6The app isn't tracking when my screen is idle — is that a bug?▾
Correct behavior. The tracker only records the active foreground window. If your screen is locked, the PC is idle, or no app is in focus, nothing is recorded. You shouldn't be charged screen time while not actively using the computer.
7Why does "OpenWith" or "WerFault" appear in my tracked apps?▾
These are Windows system dialogs that briefly become the foreground window (OpenWith = right-click "Open with" dialog; WerFault = crash reporter). Fixed in v3.0.0 — both are in the system blocklist and won't be tracked anymore.
8Why does the app show "WhatsApp" and "WhatsApp.Root" as separate entries?▾
WhatsApp on Windows uses multiple UWP processes — WhatsApp.Root is a background host. From v3.0.0, these are normalized: suffixes like .Root, .Desktop, and .BackgroundHost are stripped before recording. Old entries stay in history but new data merges correctly.
Troubleshooting
App not tracking anything
Notifications not appearing
- Check Settings → Notifications → Enable notifications is On
- Check Windows Settings → System → Notifications — make sure Digital Wellbeing is allowed
- Check Windows Focus Assist is not set to "Alarms only" or "Priority only"
- Make sure a limit actually exists for the app you're testing
Auto-update isn't working
The app checks for updates every 4 hours at startup. If you want to check manually, restart the app. If an update is available, a banner appears at the top of the interface. If no banner appears after restarting, you're already on the latest version.
App crashes on launch
Try deleting the database: open %APPDATA%\digital-wellbeing\ in File Explorer and delete wellbeing.db. Relaunch the app — it creates a fresh database automatically. Note: this clears all history.