Metadata-Version: 2.4
Name: workpulse
Version: 0.1.0
Summary: Track working time using systemd login information
Author: WorkPulse Contributors
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: paho-mqtt>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"

# WorkTracker

A Python-based tool for tracking daily working time using systemd login information. WorkTracker automatically monitors your active session and logs working time, excluding periods when your system is suspended, locked, or hibernated. Also, this tool is able to sync the data to your Home Assistant using MQTT.

## Features

- **Automatic Time Tracking**: Monitors active working time using systemd login session data
- **Smart Exclusion**: Automatically excludes suspend, locked, and hibernation periods
- **Daily Logs**: Stores daily active time summaries in a simple SQLite database
- **Systemd Integration**: Runs as a systemd user timer, updating every minute
- **Simple CLI**: Easy-to-use command-line interface
- **Lightweight**: Minimal dependencies, no external services required
- **Home Assistant**: Integrates to Home Assistant using MQTT

## AI Disclaimer

This project has been developed using a technique known as "vibe coding".
I have actually written less than 1% of the lines on this repository, as my work was
giving instructions to the AI agent. To be honest, this disclaimer was written by myself.

However, I do have large experience in Python and Linux, so everything was reviewed
and the "AI slop" is reduced due to the proper and detailed instructions I provided.

There are few weird implementations but I have decided to keep them in since it is
well documented and does not affect performance (which is not a problem here).

## Requirements

- **Python 3.10+**
- **systemd**: Linux system with systemd-logind (most modern Linux distributions)
- **loginctl**: Command-line tool for querying systemd login manager (usually pre-installed)

## Installation

### From PyPI

```bash
pip install worktracker
```

## Usage

### Initial Setup

Install and start tracking:

```bash
worktracker install
```

This command will:
- Initialize the SQLite database in `~/.worktracker/worktracker.db`
- Create and install a systemd user timer (`worktracker.timer`)
- Enable and start the timer to begin tracking
- The timer will automatically start when you log in

View current tracking status and today's summary:

```bash
worktracker status
```

If needed, you can uninstall:

```bash
worktracker uninstall
```

This removes the systemd timer and service files. Note: The database files in `~/.worktracker/` are not removed automatically. To completely remove all data, manually delete the `~/.worktracker/` directory.


## Home Assistant Integration

WorkTracker can publish daily time tracking data to Home Assistant via MQTT, allowing you to monitor your working time directly in your Home Assistant dashboard.

### Setup

1. **Configure MQTT in WorkTracker:**

   During installation, WorkTracker creates a default MQTT configuration file at `~/.worktracker/mqtt_config.toml`. Edit this file to set your MQTT broker details:

   ```toml
   broker = "192.168.1.100"  # Your MQTT broker IP address
   port = 1883
   username = ""  # Optional: MQTT username
   password = ""  # Optional: MQTT password
   topic_prefix = "worktracker"
   update_interval = 60  # Publish updates every 60 seconds
   ```

2. **Generate Home Assistant YAML Configuration:**

   ```bash
   worktracker mqtt yaml
   ```

   This command generates the Home Assistant YAML configuration with your hostname automatically filled in.

3. **Add Configuration to Home Assistant:**

   - Copy the generated YAML configuration
   - Paste it into your Home Assistant `configuration.yaml` file
   - Restart Home Assistant or reload the MQTT integration

4. **Start the MQTT Publisher:**
   To run the publisher as a service:

   ```bash
   worktracker mqtt start service
   ```

   This should be done only once and it should work automatically on next reboots.
   Or, to run it in the terminal:

   ```bash
   worktracker mqtt start local
   ```

   This allows you to simply CTRL-C and the publisher stops.


The integration creates a single sensor that displays your daily total active time formatted as hours and minutes (e.g., "2h 30m" or "45m"). The sensor updates automatically as WorkTracker publishes new data.

### MQTT Commands

- `worktracker mqtt start <mode>` - Start the MQTT publisher daemon
- `worktracker mqtt stop` - Stop the MQTT publisher
- `worktracker mqtt status` - Show MQTT configuration status
- `worktracker mqtt publish` - Manually publish status (for testing)
- `worktracker mqtt uninstall` - Disable the service and delete the publisher file.
- `worktracker mqtt yaml` - Generate Home Assistant YAML configuration


## How It Works

WorkTracker uses a systemd user timer that runs every minute. Each minute, it:

1. Checks if your session is active using `loginctl`
2. Verifies the session is not locked
3. Confirms the system is not suspended/hibernated
4. If all conditions are met, adds 60 seconds to today's total active time

The tracking is based on systemd login session state, which provides accurate information about:
- Session activity (active/inactive)
- Screen lock status
- System power state

## Limitations

- **Linux Only**: Requires systemd, which is primarily available on Linux
- **User Sessions Only**: Tracks only graphical/login sessions, not SSH sessions
- **No Historical Data Import**: Cannot import time data from other sources
- **Manual Database Access**: No built-in query interface; use SQLite tools for advanced queries

## Contributing

Contributions are welcome! Please ensure:

- All tests pass (`pytest`)
- Code coverage remains above 80%
- Code follows PEP 8 style guidelines
- New features include appropriate tests

## License

MIT License - see LICENSE file for details.

## Version

Current version: **0.1.0**
