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.
Installable builds are published with each stable release:
https://github.com/Obeo/bd1-timekeeper/releases/latest
Development builds remain available from the latest successful build of master:
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
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.
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-1Extract bd1-macos-arm64.zip, then open BD-1.app.
BD-1 checks the latest stable GitHub release at startup and once every 24 hours. When a newer version is available, the tray menu offers the download for the current operating system and displays a system notification when supported. The downloaded installer or archive is never executed automatically.
This check sends an HTTPS request to GitHub, which necessarily exposes the IP
address and HTTP headers but no BD-1 data or telemetry. Set
"update_checks_enabled": false in settings.json to disable it.
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
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"
],
"update_checks_enabled": true,
"weekly_cap_hours": 37
}To ignore more applications, add their process names to the list.
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.
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.
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-mattermostThe 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. On Windows, BD-1 also checks
the adapter description so localized or renamed connections keep their driver
identity. Add other VPN interface names 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-mattermostOn Linux, a Secret Service provider such as GNOME Keyring must be available. BD-1 does not fall back to storing the token in plaintext.
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
bd1The 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-tkUseful commands:
bd1 --report today
bd1 --report week
bd1 --push-eurecia 29
bd1 --push-eurecia 29 --remember-eurecia-password
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 testsbd1 --push-eurecia 29 first prints the report for ISO week 29 of the current
ISO year. It requires explicit confirmation before requesting any missing
Eurecia credentials and printing each update step. To select another ISO year:
bd1 --push-eurecia 29 --year 2026bd1-eurecia is a lightweight prototype for the private Eurecia web interface. It uses
Python's HTTP and cookie support directly: it does not embed Playwright or add a runtime
dependency. The password is prompted without echo.
Configure the tenant and account, then inspect week 23 of 2026:
export BD1_EURECIA_BASE_URL='https://<tenant>.eurecia.com/eurecia/'
export BD1_EURECIA_EMAIL='<account-email>'
bd1-eurecia list
bd1-eurecia --remember-password list
bd1-eurecia show --year 2026 --week 23
bd1-eurecia set-standard-week --year 2026 --week 23The base URL must include the application path, for example
https://<tenant>.eurecia.com/eurecia/. Global options such as --base-url,
--email, and --browser-session must appear before the subcommand.
The client follows Eurecia's Keycloak SSO automatically for its password and e-mail-first login forms. If the account requires MFA or another interactive identity-provider screen, import an already authenticated browser session instead:
- Open Eurecia normally in the browser and complete SSO.
- In the browser developer tools, open Network and reload Eurecia.
- Select the
api/v3/users/me/initDatarequest. - In Request headers, copy only the complete value of the
Cookieheader. - Run
bd1-eurecia --browser-session list, paste the value into the hidden prompt, and press Enter.
The same option works with show and set-standard-week:
bd1-eurecia --browser-session show --year 2026 --week 23
bd1-eurecia --browser-session set-standard-week --year 2026 --week 23
bd1-eurecia --browser-session set-standard-week --year 2026 --week 23 --applyNever paste that cookie into chat, source code, a shell command, or a committed file. The
adapter stores imported cookies only in memory and validates them immediately with
initData.
Without --apply, set-standard-week is a preview. If its current and target values are
correct, the explicit write command sets Monday through Friday to 09:00-12:00 and
14:00-18:00, saves through the observed validate=2 and btnApply=clicked legacy form
contract, reloads the timesheet, and verifies every segment:
bd1-eurecia set-standard-week --year 2026 --week 23 --applyEurecia may reuse the btnApply HTML identifier for multiple workflow buttons. The adapter
uses an unambiguous Enregistrer control when available and otherwise relies on the unique
validate field; it never triggers submission or transfer buttons. It intentionally refuses
ambiguous forms, non-POST saves, timesheets whose status cannot be established as
Nouvelle, and rows that cannot be mapped safely. It supports the observed Eurecia Keycloak
password flow and importing an established browser session, but it does not automate MFA or
additional identity-provider screens. This is an unsupported private interface whose HTML
may change; see
EURECIA_TIMESHEET_API.md for the observed contract and current
limitations.
In the weekly report, Pousser vers Eurecia replaces editable rows on the displayed working days with the displayed BD-1 work segments. The 37-hour cap is therefore applied when it is enabled. Synchronized, locked rows such as paid leave and public holidays are preserved; work for the same day is added on separate editable rows. BD-1 adds or removes editable rows as needed, saves without submitting, then reloads the timesheet and verifies the result.
The journal window reports every step, remains open on errors, and supports selecting and copying its text. Its final success line is green; failures and the manual-entry instruction are red. A verification error happens after the save request and does not imply a rollback: the timesheet may already have been changed.
The first push requests the tenant URL, account email, and password. Later pushes request
only information that is not already available. The URL and email are saved in
settings.json. The password stays in memory unless the user selects
Mémoriser dans le trousseau système or passes --remember-eurecia-password
(--remember-password for bd1-eurecia). It is then stored in Windows Credential
Manager, macOS Keychain, or the Linux Secret Service, separately for each tenant and
email address. An expired session is authenticated again automatically. A rejected saved
password is requested again and replaced only after successful authentication.
When a working day contains a raw startup network observation classified as remote,
BD-1 adds Télétravail/Remote to the first exported Eurecia segment. Existing comments
are preserved, repeated exports do not duplicate the marker, and an office export removes
only that marker. Days recorded before network observations were introduced remain
unchanged because their location is unknown.
The SQLite database and settings.json live in the user data directory resolved by
platformdirs. On macOS, the configuration file is
~/Library/Application Support/BD-1/settings.json.
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.
See CONTRIBUTING.md for development, testing, and contribution guidelines. Security reports should follow SECURITY.md. Product changes are tracked in CHANGELOG.md.