Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 29 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ shows it as a dashboard, calendar and per-app history, and stays out of the way
![Python](https://img.shields.io/badge/python-3.10%2B-3776ab)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

<img src="docs/screenshots/demo.gif" alt="AppTrackr in motion: dashboard, calendar, apps, rewards and a theme switch" width="900">
<img src="docs/screenshots/demo.gif" alt="AppTrackr in motion: dashboard, calendar, apps, focus, village harvest and a theme switch" width="900">

</div>

Expand All @@ -25,21 +25,22 @@ in front of you: time is credited only to the focused app, stops when you go idl
screen, and is written to a local SQLite database every 30 seconds. Nothing leaves your machine.

On top of the raw numbers it adds the things you reach for next: a heatmap calendar, per-app
trends and sessions, daily limits with notifications, and an optional rewards layer that turns
time in chosen apps into XP and a small village-building game.
trends and sessions, daily limits with notifications, a floating timer over other apps, and an
optional idle game that rewards staying focused in the apps you choose.

## Features

| Area | What you get |
| --- | --- |
| Tracking | Foreground-only time, idle cut-off at your last input, lock-screen detection, midnight-accurate daily totals, UWP apps resolved to the real app, elevated apps tracked by name |
| Dashboard | Live session dial, today vs. this time yesterday, week total, today by hour, last 14 days, top apps with share and category breakdown |
| In other terms | Today, this week or all time retold as Everest summit days, Apollo 11 trips, ISS laps, marathons, novels and more, each with the basis for its number |
| In other terms | Today, this week or all time as six plain counts drawn from 56 yardsticks (films, football matches, loaves of bread, ISS laps, novels and more), each with the basis for its number |
| Calendar | Month heatmap with keyboard navigation, month totals and busiest day, per-day hourly chart and app list |
| Apps | Search, period filter (today to all time), category and favorite filters, sort by time, launches or clicks |
| App detail | Today / 7 / 30 day totals, 30-day chart, recent sessions, first and last seen, longest session, rename, category |
| Control | Per-app daily limits with notifications, per-type notification switches, exclude any app (with undo), pause from the tray for a set time |
| Rewards | Optional XP, levels, streaks and a village-building game whose buildings boost future rewards |
| Focus game | Optional idle game: unbroken time in your focus apps builds flow (x1 to x3), flow powers a village that produces resources while you work, and a daily focus goal grows a streak and opens a chest |
| Floating timer | A small always-on-top clock over other apps with the time in the current app, today's total and, for focus apps, the flow tier; hides over full-screen windows |
| Desktop | Tray icon with live tooltip, launch at sign-in (starts hidden), single instance, six palettes (three dark, three light) with system switching and 8 accents |
| Motion | Fluent-timed page transitions, odometer readouts, springy switches, check marks that draw in, a gliding fader, hover fades and a tick burst on claims and builds; follows Windows *Animation effects* and can be turned off in Settings |
| Data | CSV and JSON export, consistent database backup and validated restore, automatic schema migrations |
Expand All @@ -54,14 +55,14 @@ time in chosen apps into XP and a small village-building game.
</tr>
<tr>
<td><img src="docs/screenshots/apps.png" alt="Apps"><br><sub>All apps for a period, filterable and sortable</sub></td>
<td><img src="docs/screenshots/app-detail.png" alt="App detail"><br><sub>Per-app history, limit, rewards and sessions</sub></td>
<td><img src="docs/screenshots/app-detail.png" alt="App detail"><br><sub>Per-app history, limit, focus switch and sessions</sub></td>
</tr>
<tr>
<td><img src="docs/screenshots/rewards.png" alt="Rewards"><br><sub>Level progress, pending rewards and earning apps</sub></td>
<td><img src="docs/screenshots/village.png" alt="Village"><br><sub>Village: buildings, inventory and market</sub></td>
<td><img src="docs/screenshots/rewards.png" alt="Focus"><br><sub>Focus: live flow multiplier, tier ladder, daily goal and chest</sub></td>
<td><img src="docs/screenshots/village.png" alt="Village"><br><sub>Village: harvest, production, buildings and market</sub></td>
</tr>
<tr>
<td><img src="docs/screenshots/dashboard-perspective.png" alt="In other terms"><br><sub>In other terms: the week as Voyager kilometres, marathons and Everest</sub></td>
<td><img src="docs/screenshots/dashboard-perspective.png" alt="In other terms"><br><sub>In other terms: the week as lectures, football matches and loaves of bread</sub></td>
<td><img src="docs/screenshots/settings-appearance.png" alt="Appearance settings"><br><sub>Palette gallery, accents and animation switch</sub></td>
</tr>
<tr>
Expand Down Expand Up @@ -135,18 +136,26 @@ use **Quit** from the tray menu (or <kbd>Ctrl</kbd>+<kbd>Q</kbd>) to stop it.
the dashboard and charts mark the limit.
- **Exclude an app.** Right-click it in any list and choose *Exclude from tracking*. Manage exclusions in
Settings.
- **Favorites and streaks.** Star apps you want to spend time in. A streak day needs 30 minutes in favorites.
- **Rewards.** Pick earning apps on the Rewards page or from an app's page. Milestones (30 min, 1 h, 2 h, 5 h
of focus per day) pay XP and resources you spend in the village. Turn the whole layer off in Settings.
- **Focus apps.** Pick the apps you want to spend time in (an editor, a design tool, docs) on the Focus page or
with the *Focus app* switch on an app's page. Only time in them counts toward the game.
- **Flow.** Every minute in a focus app earns focus points. Stay with it and the run climbs tiers: x1.5 after
10 minutes, x2 after 25, x2.5 after 45, x3 after 75. A short look elsewhere (3 minutes, more with taverns)
does not end a run.
- **Village.** Lumberyards, quarries, farms, mines and labs turn focus points into resources. They wait in the
harvest until you collect them on the Village page, up to what storage holds. Spend them on buildings.
- **Daily goal.** Reach your focus goal (2 h by default, set in Settings) to grow your streak and open the
daily chest. Turn the whole game off in Settings.
- **Floating timer.** While you work in another app, a small clock in the corner shows how long you have
been in it. Drag it anywhere, double-click it to open AppTrackr, right-click to hide it.
- **In other terms.** The dashboard card retells today, this week or all time against known yardsticks.
*Shuffle* shows others. Each comparison names its basis, for example "South Col to the summit and back
down: about 14 h".
*Shuffle* shows others. Each comparison names its basis, for example "football matches: two 45-minute
halves".

### Keyboard shortcuts

| Keys | Action |
| --- | --- |
| <kbd>Ctrl</kbd>+<kbd>1</kbd> to <kbd>Ctrl</kbd>+<kbd>5</kbd> | Dashboard, Calendar, Apps, Rewards, Village |
| <kbd>Ctrl</kbd>+<kbd>1</kbd> to <kbd>Ctrl</kbd>+<kbd>5</kbd> | Dashboard, Calendar, Apps, Focus, Village |
| <kbd>Ctrl</kbd>+<kbd>,</kbd> | Settings |
| <kbd>Ctrl</kbd>+<kbd>F</kbd> | Search apps |
| <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> | Pause or resume tracking |
Expand Down Expand Up @@ -265,14 +274,14 @@ apptrackr/
perspective.py yardsticks for 'In other terms' and how they are picked
core/ tracker, platform (Win32), launch watcher, click counter, autostart, limits
data/ SQLite access and migrations, queries, export/backup, app catalog, demo data
rewards/ milestone rules, reward engine, streaks
game/ village state and balance values
rewards/ focus app rules, XP and levels, daily goal and streak, rewards from 1.x
game/ flow and focus points, village production and harvest, balance values
updater/ GitHub release check and installer download
ui/ main window, theme and motion tokens, icons, views and shared widgets
assets/ logo, Lucide and AppTrackr line icons, illustrations, bundled fonts
packaging/ PyInstaller spec, Inno Setup script, app icon
scripts/ screenshot, demo animation, README art and icon generators
tests/ pytest suite (data, tracker, rewards, updater, offscreen UI)
tests/ pytest suite (data, tracker, game, upgrades, updater, offscreen UI)
```

```mermaid
Expand All @@ -283,7 +292,8 @@ flowchart LR
C[core.clicks] --> DB
DB --> Q[data.queries]
Q --> UI[ui views]
DB --> R[rewards.engine] --> G[game.state]
DB --> F[game.focus<br/>flow, focus points] --> G[game.state<br/>village, harvest]
G --> R[rewards.engine<br/>XP, streak]
R --> UI
G --> UI
T -->|snapshot| UI
Expand Down
2 changes: 1 addition & 1 deletion apptrackr/__init__.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
"""AppTrackr: foreground app usage tracker for Windows."""

__version__ = "1.1.0"
__version__ = "1.2.0"

APP_NAME = "AppTrackr"
APP_USER_MODEL_ID = "H4ch1Net.AppTrackr"
Expand Down
2 changes: 2 additions & 0 deletions apptrackr/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -141,8 +141,10 @@ def main(argv: list[str] | None = None) -> int:
return 1
if not args.demo:
from apptrackr.core import autostart
from apptrackr.rewards import rules

autostart.repair()
rules.adopt_favorites_once()
if args.demo:
from apptrackr.data import demo

Expand Down
1 change: 1 addition & 0 deletions apptrackr/assets/icons/ball.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apptrackr/assets/icons/bike.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apptrackr/assets/icons/briefcase.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apptrackr/assets/icons/car.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apptrackr/assets/icons/clapperboard.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apptrackr/assets/icons/cup.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apptrackr/assets/icons/droplet.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apptrackr/assets/icons/globe.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apptrackr/assets/icons/music.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apptrackr/assets/icons/planet.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apptrackr/assets/icons/steering-wheel.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apptrackr/assets/icons/tennis.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apptrackr/assets/icons/train.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions apptrackr/assets/icons/wind.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
42 changes: 42 additions & 0 deletions apptrackr/core/platform.py
Original file line number Diff line number Diff line change
Expand Up @@ -85,12 +85,23 @@ class _LASTINPUTINFO(ctypes.Structure):
_fields_ = [("cbSize", ctypes.c_uint), ("dwTime", ctypes.c_uint)]


class _RECT(ctypes.Structure):
_fields_ = [("left", ctypes.c_long), ("top", ctypes.c_long), ("right", ctypes.c_long), ("bottom", ctypes.c_long)]


class _MONITORINFO(ctypes.Structure):
_fields_ = [("cbSize", ctypes.c_ulong), ("rcMonitor", _RECT), ("rcWork", _RECT), ("dwFlags", ctypes.c_ulong)]


class WindowsPlatform:
"""Win32 implementation using user32/kernel32 through ctypes."""

supported = True
_DESKTOP_READOBJECTS = 0x0001
_UWP_HOST = "applicationframehost.exe"
_GWL_STYLE = -16
_WS_CAPTION = 0x00C00000
_MONITOR_DEFAULTTONEAREST = 2

def __init__(self) -> None:
from ctypes import wintypes
Expand All @@ -112,6 +123,18 @@ def __init__(self) -> None:
self._enum_proc = ctypes.WINFUNCTYPE(wintypes.BOOL, wintypes.HWND, wintypes.LPARAM) # type: ignore[attr-defined]
u.EnumChildWindows.argtypes = [wintypes.HWND, self._enum_proc, wintypes.LPARAM]
u.EnumChildWindows.restype = wintypes.BOOL
u.GetWindowRect.argtypes = [wintypes.HWND, ctypes.POINTER(_RECT)]
u.GetWindowRect.restype = wintypes.BOOL
u.GetWindowLongW.argtypes = [wintypes.HWND, ctypes.c_int]
u.GetWindowLongW.restype = ctypes.c_long
u.MonitorFromWindow.argtypes = [wintypes.HWND, wintypes.DWORD]
u.MonitorFromWindow.restype = wintypes.HANDLE
u.GetMonitorInfoW.argtypes = [wintypes.HANDLE, ctypes.POINTER(_MONITORINFO)]
u.GetMonitorInfoW.restype = wintypes.BOOL
u.GetShellWindow.argtypes = []
u.GetShellWindow.restype = wintypes.HWND
u.GetDesktopWindow.argtypes = []
u.GetDesktopWindow.restype = wintypes.HWND
k.GetTickCount.argtypes = []
k.GetTickCount.restype = wintypes.DWORD

Expand Down Expand Up @@ -167,6 +190,25 @@ def foreground_app(self) -> ForegroundApp | None:
self._last_key, self._last_app = key, app
return app

def foreground_fullscreen(self) -> bool:
"""True while the foreground window covers its whole monitor (a game, a video, a slideshow)."""
u = self._user32
hwnd = u.GetForegroundWindow()
if not hwnd or hwnd in (u.GetShellWindow(), u.GetDesktopWindow()):
return False
rect = _RECT()
info = _MONITORINFO()
info.cbSize = ctypes.sizeof(_MONITORINFO)
monitor = u.MonitorFromWindow(hwnd, self._MONITOR_DEFAULTTONEAREST)
if not u.GetWindowRect(hwnd, ctypes.byref(rect)) or not u.GetMonitorInfoW(monitor, ctypes.byref(info)):
return False
m = info.rcMonitor
exact = (rect.left, rect.top, rect.right, rect.bottom) == (m.left, m.top, m.right, m.bottom)
covers = rect.left <= m.left and rect.top <= m.top and rect.right >= m.right and rect.bottom >= m.bottom
# A maximized window overhangs the monitor by its borders but keeps its title bar.
captionless = (u.GetWindowLongW(hwnd, self._GWL_STYLE) & self._WS_CAPTION) != self._WS_CAPTION
return exact or (covers and captionless)

def idle_seconds(self) -> float:
info = _LASTINPUTINFO()
info.cbSize = ctypes.sizeof(_LASTINPUTINFO)
Expand Down
8 changes: 8 additions & 0 deletions apptrackr/core/tracker.py
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,14 @@ def current_app_id(self) -> int | None:
"""Lock-free read for hot paths such as the mouse hook."""
return self._app_id

def foreground_fullscreen(self) -> bool:
"""True while a full-screen window is in front (Windows only)."""
check = getattr(self._platform, "foreground_fullscreen", None)
try:
return bool(check()) if check else False
except OSError:
return False

def snapshot(self) -> Snapshot:
with self._lock:
now = self._clock()
Expand Down
Loading
Loading