How waishnav/watcher works
Project type and purpose
• This is a minimal open‑source, cross‑platform CLI application called “Watcher” that tracks screen‑time by polling the operating system for idle time (xprintidle) and active window events (xdotool), logs them, and provides summaries (day/week).
File structure
• Top level:
• install / uninstall / update scripts – OS‐level bootstrap and teardown.
• src/Watcher – Python package containing core logic.
• src/bin/watcher – CLI entry point.
• misc/export_to_2.0 – migration utilities for version 2.0 logfile format.
• src/Watcher sub‑modules:
• get_windows.py: invokes external tools to capture current window and idle time.
• time_operations.py: computes durations from timestamps.
• watch_log.py: appends events to a local logfile.
• analysis.py: reads logfile and aggregates data into day/week summaries.
• afk.py: (planned) filters out AFK time.
• commands.py: parses CLI arguments and dispatches to recording vs reporting.
Insights from README
• External dependencies: xprintidle and xdotool.
• Outputs: CLI reports with ASCII tables or simple text summaries.
• No database—logfile is the only persistence.
• Future: Go migration branch, GUI planned for stars.
Main components & interactions
a. Components:
1. User (CLI invocation)
2. CLI Frontend (src/bin/watcher + commands.py)
3. Core Processor (Watcher package modules)
• get_windows → polls OS
• time_operations → computes durations
• watch_log → writes to logfile
• analysis → reads logfile to produce reports
• afk → filters AFK time (future)
4. Local Logfile (e.g., ~/.watcher/log.txt)
5. OS-level External Services (xprintidle, xdotool)
6. Bootstrap Scripts (install, uninstall, update)
b. Relationships & data flow:
• CLI Frontend → Core Processor modules (invoke record or report flows).
• get_windows ↔ External Tools (shell calls to gather window/idle time).
• get_windows → time_operations → watch_log → Logfile (persist events).
• analysis → Logfile (read persisted data) → commands → CLI (render summary).
• afk (in the pipeline) intercepts get_windows/time_operations to filter out idle.
c. Architectural patterns/design principles
• Modular separation of concerns: I/O (get_windows), processing (time_operations), persistence (watch_log), reporting (analysis), CLI (commands).
• Single source of truth: logfile as append‑only event store.
• CLI Front Controller: commands.py routes user actions to modules.
d. Key technologies/frameworks
• Python3 standard library
• External OS utilities: xprintidle, xdotool
• Bash scripts for install/uninstall/update
Detailed capturing of architecture
• Container “Watcher Python Package” containing: get_windows, time_operations, watch_log, analysis, afk.