Asami Companion

Native desktop client (Windows and Linux) for the named quotas and timers of the Asami agent accesses an operator is allowed to manage. The Asami server is the only authority for accesses, quotas, timers and permissions: the client only displays them and forwards explicit user actions through the eight public Companion MCP tools.

• One C++20 code base, one version cycle for both platforms.
• GUI: wxWidgets 3.2 (GTK 3 on Linux, MSW on Windows).
• OAuth 2.1 Authorization Code + PKCE S256 in the external browser, loopback callback on 127.0.0.1, idempotent Dynamic Client Registration.
• Refresh tokens only in the OS secret store (libsecret / Credential Manager); never in plain text.
• One MCP Streamable HTTP session per process, protocol ping every 20 s.

One command

Everything is driven by the Makefile (GNU make):

Command	Result
make deps-debian	installs every Debian 13 prerequisite (once, uses sudo)
make	Linux build and the full test suite
make flatpak	Flatpak package in build-flatpak/
make windows	Windows x86_64 EXE in build-win/asami-companion.exe; builds the pinned static dependencies into .deps/windows first if they are missing
make windows-test	Windows test suite and GUI smoke test under Wine
make gnome-extension	GNOME Shell extension ZIP build-extension/asami-companion@asami.rocks.shell-extension.zip and its SHA-256
make clean / make distclean	removes build trees / also the Windows dependency prefix

JOBS sets the parallelism (default: number of CPUs). The Windows dependency build uses DEPS_JOBS (default 2): wxWidgets needs about 1.5 GB of memory per compile job, so a 4 GB machine should not go higher.

Layout

Path	Content
src/core/	Platform-neutral protocol logic: origin, configuration v1, PKCE, discovery, DCR, OAuth, MCP session, typed Companion API, instance switch
src/platform/	OS services: secret store, loopback listener, libcurl HTTP, paths and time zone, GNOME keep-above client, autostart
src/app/	Application controller, token custody, presentation (no GUI toolkit)
src/ui/	wxWidgets window
tests/	doctest unit and end-to-end tests
packaging/	Linux desktop identity, Flatpak manifest, Windows dependency script and icon resource
packaging/icons/	The Asami logo at 16–512 px, regenerated by tools/make-icons.sh <logo_asami.png>

Using the window

The window shows, read-only, exactly what the WMI quota sticky shows when it is expanded: the icons of the agents with no timer running (name on hover), then one row per agent with a running timer, with a progress pill and the remaining time for each armed timer (quota label and deadline on hover).

The window has no title bar and is as small as its content. Drag it with the left button. Every command is in the right-click menu: Toujours au premier plan, Actualiser, Gérer les quotas & timers…, Préférences… and Quitter. The preferences window (instance, Changer de serveur…, authorization, start with the session, keep on top) opens centred, and by itself while the installation is not set up.

Gérer les quotas & timers… opens a separate window, centred, with the same editor as the WMI Agents view for every agent that already has a quota: add a quota (up to five), rename it (not while its timer runs), delete it (inline confirmation), arm its timer once the server has interpreted the value (3h14, 13:55, lun 9:00…) and cancel a running timer. Every change is read back from the server before it is shown as done; an uncertain result is never replayed, the state read back is shown instead. An agent's first quota is still created in the WMI.

Changer de serveur… switches the installation to another Asami instance (QA, production…). For an authorized installation, revoke it first in the WMI of the current instance, then confirm: the local authorization is erased and the new instance asks for a new authorization.

build/companion-preview OUT.png [sticky|message|empty] renders the window with fixture data and build/companion-preview - quotas opens the management window over an in-memory fake, for development only (never installed).

Linux build (Debian 13)

sudo apt install g++ cmake ninja-build pkg-config libwxgtk3.2-dev libsecret-1-dev \
  libcurl4-openssl-dev nlohmann-json3-dev doctest-dev gnome-keyring dbus-bin xvfb
cmake -S . -B build -G Ninja
cmake --build build
tests/run-with-keyring.sh ctest --test-dir build --output-on-failure

tests/run-with-keyring.sh runs the tests inside an isolated session bus with a throw-away, unlocked gnome-keyring, so the secret-store, keep-above and autostart tests talk to real D-Bus services. Without it those tests prove the fail-closed behaviour only. gui_smoke opens the window under Xvfb and closes it.

Flatpak

Application ID rocks.asami.AsamiCompanion, runtime org.freedesktop.Platform//26.08. The host needs flatpak, flatpak-builder and bzip2.

flatpak --user remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak --user install flathub org.freedesktop.Platform//26.08 org.freedesktop.Sdk//26.08
flatpak-builder --user --force-clean build-flatpak packaging/flatpak/rocks.asami.AsamiCompanion.yml

Session bus policy is exact: talk to rocks.asami.AsamiCompanion and org.freedesktop.secrets, see org.gnome.Shell; no own-name, no generic bus access, no filesystem permission. Keep-above on GNOME/Wayland requires the separate Asami Companion GNOME Shell extension; without it the window is never claimed to stay on top.

GNOME Shell extension (keep-above on GNOME/Wayland)

make gnome-extension builds the ZIP bundle (UUID asami-companion@asami.rocks, GNOME Shell 48 and 50). Install it for your account, then enable it:

gnome-extensions install --force asami-companion@asami.rocks.shell-extension.zip
gnome-extensions enable asami-companion@asami.rocks

Update by installing the next ZIP the same way; gnome-extensions disable / gnome-extensions uninstall asami-companion@asami.rocks turn it off or remove it. Without the extension the app works normally and says that keep-above is not guaranteed.

Windows (cross-build from Linux)

sudo apt install g++-mingw-w64-x86-64-posix mingw-w64-tools wine64
packaging/windows/build-deps.sh "$HOME/win-deps"
cmake -S . -B build-win -G Ninja -DCMAKE_TOOLCHAIN_FILE=cmake/mingw-w64-x86_64.cmake \
  -DCOMPANION_WIN_DEPS="$HOME/win-deps" -DCMAKE_PREFIX_PATH="$HOME/win-deps"
cmake --build build-win

The EXE links libgcc, libstdc++, wxWidgets and libcurl (Schannel) statically.

Icon

Every surface shows the Asami logo (the image of the WMI): the EXE icon (packaging/windows/asami.ico, Explorer, Start menu, pinned task bar), the window icon of every window (title bar, task bar, Alt-Tab; embedded at build time by cmake/embed_icons.cmake), and on Linux the hicolor theme icon rocks.asami.AsamiCompanion (launcher, GNOME overview and dock). All dependency archives are pinned by official URL and SHA-256.

Moving from Companion 1.0.0 (clean start)

Since the Lot E release the Companion uses the rocks.asami identities (rocks.asami.AsamiCompanion, extension asami-companion@asami.rocks). It is a new application for the desktop: nothing of 1.0.0 is migrated, on purpose. Remove the old one by hand, then install the new one and authorize it once.

1. In the WMI, Companion view: revoke the old installation's access.

2. Linux (Flatpak 1.0.0):

   flatpak uninstall --delete-data net.lodlp.AsamiCompanion
   gnome-extensions uninstall asami-companion@lodlp.net   # if it was installed
   

   Then remove the "Asami Companion authorization" entry from the keyring (GNOME "Passwords and Keys"), and log out and back in once.

3. Windows: quit the old Companion, delete its executable and the folder %LOCALAPPDATA%\Asami\Companion (the new version reuses this path, so a stale 1.0.0 configuration would otherwise ask for a re-authorization), and remove the net.lodlp.AsamiCompanion/... entries in Credential Manager (Windows Credentials). Re-enable "start with the session" in the new Companion if you want it: the AsamiCompanion Run entry then points to it.

4. Install and launch the new Companion, authorize it once.

Configuration

The only setting is the operator-owned HTTPS origin of the Asami instance (MCP_PUBLIC_URL), entered on first launch; there is no default instance. Non-secret configuration lives in %LOCALAPPDATA%\Asami\Companion\config.json (Windows) or $XDG_CONFIG_HOME/config.json inside the Flatpak sandbox.