snooper_pkg

A transparent, Windows-only foreground-application usage tracker — for your own awareness of where your time goes, or shared accountability with someone you choose. Not secret surveillance.

snooper_pkg records a simple, useful signal: which application and window is in the foreground, and for how long. It is intended to make productive-work sessions easier to review together, without capturing the contents of that work.

Time away from the keyboard is treated separately from active foreground use. For example, if a browser remains open while someone is away, that interval can be reported as idle time rather than browser activity.

Most people should install the Windows application below; the Python package is for development and contribution.

Privacy boundaries

Snooper is designed to be installed by the person whose time it measures. It is not intended to record:

  • keystrokes
  • screenshots
  • messages
  • passwords
  • complete webpage contents
  • detailed personal content

Window titles can themselves contain sensitive information. Title display is controlled by the SHOW_WINDOW_TITLES setting; it is fixed at build time in the installed application, but can be changed by anyone running from source.

Installing on Windows

Download the latest Snooper-Setup-*.exe from the GitHub Releases page and run it.

  • No administrator rights are required; Snooper installs per-user.
  • You can optionally select “Start Snooper automatically when I sign in” during setup.
  • Snooper starts in the system tray; there is no separate window to open.

To uninstall, use “Uninstall Snooper” from the Start Menu or Windows Settings. Uninstalling removes the application but does not delete your session database (see Data storage below).

Using Snooper

Right-click the tray icon to:

  • show the last completed session’s report
  • show stats for the current session
  • pause monitoring (for 15 minutes, 30 minutes, or a custom duration)
  • resume monitoring immediately
  • exit

Pausing ends the current session; monitoring resumes automatically after the pause duration, starting a new session.

Data storage

Snooper stores its database and log file under your Windows user profile, at %LOCALAPPDATA%\Snooper.

  • snooper.db — session, foreground-window, and process data. Entries older than the configured retention period are deleted automatically.
  • snooper.log — application log file.

Uninstalling Snooper does not delete this folder. To remove all data, delete %LOCALAPPDATA%\Snooper manually after uninstalling.

Features

Snooper currently provides:

  • automatic monitoring on startup
  • monitoring sessions stored in SQLite
  • foreground application and window interval tracking
  • Windows idle detection
  • process start and stop events
  • cleanup of old session data beyond a configurable retention period
  • pause and automatic resume, from the system tray
  • session report generation
  • a table-style report window
  • single-instance guard (a second launch exits without opening a duplicate)
  • clean application exit

Requirements (running from source)

  • fastcore
  • fastlite
  • pandas
  • psutil
  • Pillow
  • platformdirs
  • pystray on Windows
  • pywin32 on Windows

tkinter is not listed as a PyPI dependency because it is part of Python’s standard library; confirm it is available in the target Python installation.

These are only needed when running snooper_pkg from source. The Windows installer bundles all dependencies and requires nothing further.

Development installation (contributors)

From the project root, install the package in editable mode:

python -m pip install -e .

Export notebook changes into the package with:

nbdev-export

Run notebook tests with:

nbdev-test

Use the combined preparation command before committing:

nbdev-prepare

Running from source

After installing in editable mode and exporting the notebooks (see above), run:

python -m snooper_pkg.main

This creates a [MonitorController](https://sayanbanerjee32.github.io/snooper_pkg/monitoring_controller.html#monitorcontroller), starts monitoring, and enters the system-tray loop, showing the most recently completed session’s report on startup. Only one instance of Snooper can run at a time; a second launch exits immediately.