Metadata-Version: 2.4
Name: swaybeing
Version: 0.1.0
Summary: Screentime monitoring app for Sway/i3
Author-email: OliMoli <olimoli@disroot.org>
License-Expression: LGPL-3.0-or-later
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: i3ipc>=2.2.0
Requires-Dist: pydantic>=2.13.0
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: platformdirs>=4.9.0
Requires-Dist: click>=8.3.0
Requires-Dist: tabulate>=0.10.0
Dynamic: license-file

<!--
vim: ft=markdown softtabstop=2 shiftwidth=2
-->

# Swaybeing
A simple daemon for Sway/i3 to track per-app screen time

> [!NOTE]
> This program is in an early development phase.
> The API and CLI is subject to changes.

# Screenshots
![](https://codeberg.org/OliMoli/swaybeing/raw/branch/main/img/db-show.png)

# How it works
Swaybeing monitors the time you spend in each app. It subscribes to window changes through the i3/Sway IPC socket. When a window is closed or the focus changes to a different app, it compares current timestamp with the timestamp snapshotted when you started using the app and adds it to a write queue. The queue is then written to a database (each 5 minutes by default).

Usage stats are stored in an SQLite database. Each day is divided into equal time periods (of the length of 3 hours by default). App usage data is split between those periods. This is a balance between inefficient storing of linear app usage timestamps and not dividing them at all. Changing the period length will only take effect next day if current day already contains usage data.

Daylight savings are also handled clearly. Swaybeing internally uses the UTC timezone, which is later visually converted to your current timezone when running the `swaybeingctl db show` command.

# Installation

## Nix
To test it out, you can enter a temporary nix shell:
```nix
nix shell git+https://codeberg.org/OliMoli/swaybeing
```

For a permanent installation, first add Swaybeing to your flake:
```nix
{
  inputs = {
    # ... other inputs

    swaybeing = {
      url = "git+https://codeberg.org/OliMoli/swaybeing";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
  
  # ... rest of your flake

  outputs = inputs @ { self, nixpkgs, ... }: {
    # example host, replace with your own!
    nixosConfigurations.example = nixpkgs.lib.nixosSystem {
      # ... rest of the system

      specialArgs = {
        # This is important!
        inherit inputs;
      }
    };
  };
}
```

Then, import the module and set `services.swaybeing.enable = true;`. It will automatically install the package and configure the systemd user service.
```nix
{ inputs, ... }: {
  modules = [
    inputs.swaybeing.nixosModules.default # System module (appiles to all users)
    inputs.swaybeing.homeModules.default # Home module (applies to a single user)
  ];

  services.swaybeing = {
    enable = true; # install the package and enable the autostart service

    # Optional values with examples:
    package = inputs.swaybeing.packages.${pkgs.system}.default; # specify a custom Swaybeing package to use instead
    extraOptions = [ "-l", "debug" ]; # extra command line arguments to be passed to the swaybeingd command
    systemdTargets = [ "sway-session.target" ]; # systemd target which triggers the start of swaybeingd; highly recommended to set

    # Home Manager only: generate config.json
    config = {
      period_length = 24;
      commit_interval = 60;
    };
  };
}
```

If you prefer not to use the module, you can install the packages manually instead:
```nix
{ pkgs, inputs, ... }:
{
  environment.systemPackages = [ inputs.swaybeing.packages.${pkgs.system}.default ]; # NixOS
  home.packages = [ inputs.swaybeing.packages.${pkgs.system}.default ]; # Home Manager
}
```

Once Swaybeing gets more stable I'll PR it to Nixpkgs.

## Virtual env
To test it out, clone the repo and source the `venv-setup` script, or `venv-setup.fish` if you use fish.

It will automatically create a temporary venv, drop you into it and source shell completions.

## PyPI
A PyPI package is available [here](https://pypi.org/project/swaybeing)

# Setup
Put this line in your Sway/i3 config:
```
exec --no-startup-id swaybeingd
```
> [!NOTE]
> If you're a NixOS/Home Manager user, there's already a systemd unit prepared. See above for more info.

You can also add Swayidle hooks to pause monitoring screentime when you're idle:
```
# Sample screen lock hook
lock 'swaybeingctl msg pause; your-locker; swaybeingctl msg resume'
unlock 'swaybeingctl msg resume; your-unlocker'
before-sleep 'loginctl lock-session'

# Stop monitoring after 1 minute of idling
timeout 60 'swaybeingctl msg pause' resume 'swaybeingctl msg resume'
```
or if you use Home Manager:
```nix
{ config, pkgs, inputs, ... }:
let
  swaybeing = "${inputs.swaybeing.packages.${pkgs.system}.default}";
  # or
  swaybeing = config.services.swaybeing.package;

  swaybeingctl = "${swaybeing}/bin/swaybeingctl";
in
{
  services.swayidle = {
    enable = true;
    events = {
      # Sample screen lock hook
      lock = "${swaybeingctl} msg pause; your-locker; ${swaybeingctl} msg resume";
      unlock = "${swaybeingctl} msg resume; your-unlocker";
      before-sleep = "${pkgs.systemd}/bin/loginctl lock-session";
    };

    timeouts = [
      {
        # Stop monitoring after 1 minute of idling
        timeout = 60;
        command = "${swaybeingctl} msg pause";
        resumeCommand = "${swaybeingctl} msg resume";
      }
    ];
  };
}
```

# Usage
The `swaybeingd` command launches the main daemon.

Use `swaybeingctl` to query the database and communicate with the daemon.

Basic commands:
- `swaybeingctl db show`: show recorded usage information
- `swaybeingctl msg pause`: pause monitoring time
- `swaybeingctl msg resume`: resume monitoring time

More commands can be listed by passing the `--help` argument.

# Config
The config file is located at `$XDG_CONFIG_HOME/swaybeing/config.json`. Config location can be overridden with the `-c` flag
> [!NOTE]
> Home Manager users can define the config options in the Home module documented above.

| Key               | Default value                            | Description                                                                                                    |
| ----------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `autocommit`      | `false`                                  | Automatically write all changes after a window event (disables internal write queue).                          |
| `commit_interval` | `60`                                     | How often in seconds to write the changes to the database. Set to `0` to disable this feature.                 |
| `database`        | `"$XDG_DATA_HOME/swaybeing/database.db"` | Where to store the database. Can be overriden with the `-d` flag.                                              |
| `period_length`   | `3`                                      | Time period length in hours. Must be divisible by 24. Lower = more accuracy. See "How it works" section above. |
| `socket`          | `"$XDG_RUNTIME_DIR/swaybeing.socket"`    | Socket path. Can be overriden with the `-s` flag.                                                              |

All paths in the config allow enviromnent variable and home directory (~) expansion.

> [!WARNING]
> It is not recommended to set both `"autocommit" = false` and `"commit_interval" = 0` at the same time, or the database will only be updated at exit or on `swaybeingctl msg commit`.

# Shell completions
> [!NOTE]
> Nix users can skip this section since the Nix package already generates proper shell completions.

Swaybeing uses [Click](https://click.palletsprojects.com) as its argument parsing engine. According to the [docs](https://click.palletsprojects.com/en/stable/) here are the commands to generate completions:
```shell
_SWAYBEINGD_COMPLETE=shellname_source swaybeingd
_SWAYBEINGCTL_COMPLETE=shellname_source swaybeingctl
```

Replace "`shellname`" with either `bash`, `zsh` or `fish`.

To permanently install a bash/zsh completion, save the completions to files by adding `> filename` to the end of the commands above and add `source filename` to your .bashrc/.zshrc (obviously replace "`filename`" with your own destination filename)

For fish, put the completions in `~/.config/fish/completions/command_name.fish`, replacing "`command_name`" with `swaybeingd` or `swaybeingctl`

# Contributing
See [CONTRIBUTING.md](https://codeberg.org/OliMoli/swaybeing/src/branch/main/CONTRIBUTING.md).

# License
This project is licensed under the [LGPL-3.0-or-later](https://codeberg.org/OliMoli/swaybeing/src/branch/main/LICENSE) license.
