WorkProof

Local-first desktop activity tracker and report generator for Windows and Linux. WorkProof runs quietly in the background, captures active window/process activity, idle times and file events for a configurable Projects folder, stores data locally in SQLite, and produces HTML/PDF reports with charts.

For full developer and packaging docs see the docs/ directory. This README gives a quick overview and pointers to the installation and usage guides.

Highlights

• Local-first: data stored on your machine only
• Tracks active window, running processes, idle time and project file events
• Daily summarizer with HTML and optional PDF export (Jinja2, Matplotlib/WeasyPrint)
• Simple SQLite storage with retention/purge utilities
• Packaging helper scripts for Windows (.exe) and Linux

Quick start (recommended)

1. Create and activate a virtual environment

   Windows PowerShell:

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1

2. Install the package in editable mode and install requirements

   pip install -e .
   pip install -r requirements.txt

3. Run the smoke test (short sampling run):

   python run_smoke_test.py

4. Start the tracker (foreground):

   python -m workproof.main

5. Generate a report (example):

   python -m workproof.report_generator --date today --out reports/today.html

Helpful shortcuts and files

• run_smoke_test.py — quick local check to verify tracking
• build_win_exe.ps1 / build_linux.sh — packaging helpers (PyInstaller specs included)
• examples/ — example scripts for common tasks (report generation, import)
• docs/ — detailed docs: installation, packaging, autostart, privacy, usage

Testing

Run the test suite with pytest:

pytest -q

Developer notes

• Source is under src/workproof/ (package name workproof).

• To run modules directly without installing, ensure src is on PYTHONPATH, e.g.:

  $env:PYTHONPATH = "$(Resolve-Path .\src)"
  python -m workproof.main

Contributing

Contributions are welcome. Please open issues or PRs. See docs/usage.md and docs/packaging.md for guidance when changing behavior that affects reports or packaging.

License

MIT — see LICENSE.