BD-1

BD-1 is a local desktop companion that observes user activity and suggests a daily or weekly time report. It is not a clock-in system: it stores factual observations and recomputes suggestions on demand.

Installation

Installable builds are published from the latest successful build of the master branch:

https://github.com/Obeo/bd1-timekeeper/releases/tag/build/master

Download the asset matching your operating system:

• Windows: bd1-windows-x86_64.exe
• Linux: bd1-linux-x86_64.tar.gz
• macOS: bd1-macos-arm64.zip

Windows

Run bd1-windows-x86_64.exe and follow the installer. The application is installed as BD-1.exe and can be launched at the end of the setup.

If autostart was enabled in a previous installation, reinstalling in a different folder updates the existing Windows startup entry to the new executable location.

Linux

Extract bd1-linux-x86_64.tar.gz, then run the BD-1 executable from the extracted folder:

tar -xzf bd1-linux-x86_64.tar.gz
./BD-1/BD-1

macOS

Extract bd1-macos-arm64.zip, then open BD-1.app.

Settings

BD-1 creates a settings.json file in the user data directory resolved by platformdirs. On Windows, this is typically:

%LOCALAPPDATA%\BD-1\BD-1\settings.json

idle_ignored_process_names

The idle_ignored_process_names setting lists process names that should prevent BD-1 from turning keyboard and mouse inactivity into a break. This is useful for meeting applications where the user may be working without touching the keyboard or mouse.

By default, BD-1 includes the Zoom meeting processes aomhost64.exe on Windows and cpthost on Linux:

{
  "lunch_automatic_work_resume_time": "13:58",
  "idle_ignored_process_names": [
    "aomhost64.exe",
    "cpthost"
  ],
  "weekly_cap_hours": 37
}

To ignore more applications, add their process names to the list.

lunch_automatic_work_resume_time

The lunch_automatic_work_resume_time setting controls the time used when BD-1 detects activity during the protected lunch window. For example, if the computer wakes up at 13:20 but this value is set to 13:58, BD-1 keeps the lunch break open until 13:58. Use the HH:MM format. Missing or invalid values fall back to 13:58. The value must be after 12:00 and no later than 14:00.

weekly_cap_hours

The weekly_cap_hours setting controls the weekly target used when the Plafond 37h option is enabled in the weekly report. It defaults to 37. For local testing, it can be set to a lower value such as 20. Invalid or non-positive values fall back to 37.

Mattermost status

BD-1 can set your Mattermost custom status to In the office or Working remotely. Open Configurer → Intégration Mattermost from the tray menu, then enter the HTTPS URL of your Mattermost server and your personal access token. You can also configure it from a terminal:

bd1 --configure-mattermost

The URL and VPN interface patterns are stored in settings.json; the token is stored in Windows Credential Manager, macOS Keychain, or the Linux Secret Service. Settings changed from the tray UI take effect immediately.

BD-1 checks the network at startup and once per hour. A successful resolution of intranet.obeo.fr through a physical interface means office; a failed resolution or a route through OpenVPN means remote. Common tun, tap, utun, ovpn, OpenVPN, and Wintun interface names are recognized. Add renamed VPN interfaces to vpn_interface_patterns in settings.json, using case-insensitive glob patterns.

An active custom status set manually in Mattermost takes precedence over BD-1. BD-1 statuses expire at the end of the local day and are refreshed the following day. To opt out:

bd1 --disable-mattermost

On Linux, a Secret Service provider such as GNOME Keyring must be available. BD-1 does not fall back to storing the token in plaintext.

Development

python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
bd1

The base install supports reports, settings, and persistence. To run the tray application and activity detection, install the desktop extra:

python -m pip install -e ".[desktop]"

On Linux, pynput depends on evdev, which may compile locally. If that build fails with Python.h: No such file or directory, install the Python development headers for your distribution, then retry the desktop extra.

The report windows use tkinter, which is packaged separately by some Linux distributions. On openSUSE, install it if bd1 fails with No module named 'tkinter':

sudo zypper install python313-tk

Useful commands:

bd1 --report today
bd1 --report week
bd1 --mark-working
bd1 --mark-break
bd1 --diagnose-desktop
bd1 --profile-runtime
bd1 --no-activity-monitor
bd1 --enable-autostart
bd1 --disable-autostart
bd1 --autostart-status
bd1 --configure-mattermost
bd1 --disable-mattermost
python -m unittest discover -s tests

The SQLite database and settings.json live in the user data directory resolved by platformdirs.

License

Copyright (c) 2026 Obeo.

BD-1 is made available under the Eclipse Public License 2.0. See LICENSE for the complete terms and NOTICE for project copyright and redistribution information.

The application includes third-party dependencies under their own licenses. See THIRD_PARTY_LICENSES.md for the dependency inventory.

Contributing

See CONTRIBUTING.md for development, testing, and contribution guidelines. Security reports should follow SECURITY.md. Product changes are tracked in CHANGELOG.md.