========
WorkMuch
========

Copyright (c) 2011 Joseph Lisee
All rights reserved.


License information
-------------------

The OSI MIT License is used.  Please See the file "LICENSE" for information on
the history of this software, terms & conditions for usage, and a DISCLAIMER OF
ALL WARRANTIES.


About
-----

This tool records which program/window you are currently using and your idle
time at a configurable sample rate so you can analyze what you actually use
your computer for.

- Linux: uses X11 (`python-xlib` + `libX11`/`libXss`)
- macOS: defaults to native framework APIs (AppKit + Accessibility + CoreGraphics)


Dependencies
------------

On Linux, install the required X11 libraries using::

    sudo apt-get install libX11-dev libXss-dev

This project now uses `uv` to manage the Python runtime and dependencies from
`pyproject.toml`.
All Python source code now lives under the `workmuch` package, including
`workmuch.pytime`.

macOS permissions
-----------------

The native macOS backend needs Accessibility permission to read the focused
window title. Without this permission:

- app name and idle time still work
- window title is returned as an empty string

The backend can be selected with the environment variable:

- `WORKMUCH_MAC_BACKEND=native` (default)
- `WORKMUCH_MAC_BACKEND=subprocess` (temporary fallback during migration)


Usage
-----

1. Install dependencies into the project environment:

       uv sync

2. Run the program:

       ./run.sh --help

Run `workmuch.pytime` with your preferred options and it will record data into
the `~/.workmuch` directory.

Go tray collector
-----------------

The Go entrypoint now runs as a tray app by default:

    ./run_go.sh

When launched this way, logging starts immediately and continues in the
background. The tray menu includes:

- `About` (opens a basic about screen)
- `Quit`

Use QA console mode to bypass tray UI and stream CSV to stdout:

    ./run_go.sh --qa-console

For manual QA, use console mode to avoid writing any files:

    ./run.sh --qa-console

In this mode, activity rows are emitted to stdout as CSV and no work log or
error log files are written.

Tests
-----

Run tests with:

    ./test.sh -q

macOS backend benchmark
-----------------------

To compare native vs subprocess backend query overhead on macOS:

    uv run python scripts/benchmark_macos_backends.py --iterations 500