Instead of living in a browser tab, soloops also runs as a standalone app with a dock icon, a menu bar and a tray item — a Tauri window onto the same interface, around 10 MB, using the macOS WebView rather than shipping its own Chromium.
npm run app # start the app in development mode
npm run app:build # build soloops.app and a DMGThe result lands in
apps/desktop/src-tauri/target/release/bundle/macos/soloops.app — drag it to
/Applications once and you're done.
What the app adds on top of the web UI:
-
Starting the containers itself. On launch it checks whether web and API respond. If they don't, it starts Docker Desktop and runs
docker compose up -d; the splash screen reports what it is waiting for. Closing the window leaves the containers running so the worker keeps syncing calendars and mail — quit them from the tray menu. -
Keyboard shortcuts. ⌘1 to ⌘9 jump to the modules, ⌘R reloads, ⌘⇧M fetches the inbox, ⌘⇧P opens the port overview, ⌘⇧Z shows the time widget.
-
Port overview (⌘⇧P or tray). The same thing as
npm run ports, in a window: which service listens on which port, where it comes from, and a button to stop it. The app shells out toscripts/ports.shfor this — the logic exists in exactly one place. -
Time widget (⌘⇧Z or tray). A frameless pill on top of everything: a dot that says whether the clock runs, the project key, the elapsed time. The whole pill is handle and switch at once — drag it and it moves, click it and it folds out; what tells the two apart is whether the pointer travelled more than four pixels. Letting go snaps it to the nearest of eight resting places — the four corners and the middle of the four edges — so it lands out of the way instead of in the middle of what is being read. Where it sat, whether it was unfolded and whether it was on at all survive a restart in
data/tracker.json.It also stays on the screen it was dropped on. That needs saying, because the obvious implementation gets it wrong: tao reports a monitor's position as its bounds times that monitor's backing scale, and a window's position times the scale of the screen the window is on. Put a 2× laptop display next to a 1× monitor and those two numbers are no longer in the same coordinate system — so the geometry in
tracker.rsis done entirely in points, the screen a widget belongs to is the one containing its centre, and the name of that screen is remembered indata/tracker.json. A monitor that has been unplugged is simply gone, and then the first screen takes over.It stays where it is put: it joins every space rather than waiting on the one it was opened on, and a thread brings it back whenever macOS has hidden it along with the rest of the app (⌘H, "Hide Others"). That thread keeps its hands off while the widget is being dragged — macOS reports a window crossing a screen boundary as hidden for a moment, and answering that by snapping it back to its anchor every three seconds is what a flickering widget looks like. The one thing that still covers it is another app's fullscreen window. Switching it off is a decision and stays one — the button for that sits inside the unfolded panel, not next to the fold arrow where a misclick used to make it look crashed.
Unfolded it lists the active projects by client with the hours that are not on an invoice yet; one click starts the clock. While it runs it shows the commits that have landed in the window so far — the ones that will become the service description on the invoice, see Modules. Stopping is one button; the commits are filled in a few minutes later, because the push comes after the clock.
The widget talks to the API through Rust and never sees the
SERVICE_TOKEN. Its commands hang off that one window (capabilities/tracker.json): read the timer, start it, stop it, read the project list, read the commits of an entry, fold, snap, disappear. Nothing else, and no other window. -
Backup into iCloud (Ansicht → Backup & iCloud … or tray). One archive per run holding a
pg_dumpof the database and a copy ofdata/, written into a folder that syncs itself — iCloud Drive by default (~/Library/Mobile Documents/com~apple~CloudDocs/soloops-backup), any other folder if one is chosen. Off until a folder is confirmed; once on, every 24 hours by default, keeping the newest 14 archives.The database itself stays local, deliberately. Pointing Postgres at a synced folder loses it: iCloud writes when it feels like it, evicts files it believes are cold, and resolves a conflict by keeping both versions side by side. The failure does not show up on the day it is caused — it shows up weeks later as a cluster that will not start. Snapshots into that folder cannot corrupt what they copy.
The archive is built under
.<name>.partand renamed into place at the very end, because iCloud starts uploading the moment a file appears. A dump of under a kilobyte is treated as a failed run and thrown away — otherwise a stack that was not running would rotate away fourteen good snapshots over fourteen days. A failed run leaves the timestamp where it was, so the next tick tries again instead of waiting out the interval.Onto a new Mac: clone the repository, copy the
.env,npm run up, then open this window and restore the newest archive. Restoring overwrites what is there — the button arms on the first click and does it on the second, like the port window's. Files go back first and the database last, and afterwards the interface needs a reload (⌘R). Settings and status live indata/backup.json; the window's commands hang off that one window (capabilities/backup.json), andpg_dump,tarandpsqlrun in Rust — the page knows neither the.envnor the database. -
Activity recording. One sample every 20 seconds: which app is in front, what its window is called, how long nobody has typed. Off by default — the checkbox sits in the tray and under Ansicht and takes effect immediately. On first run macOS asks for Accessibility permission (System Settings > Privacy & Security); without it, nothing is recorded. Details under Activity.
-
Follow-up reminders. A lead whose follow-up falls due becomes a macOS notification — once per date, and only between 8 and 22. Details under Follow-ups.
-
Connecting Claude. Einstellungen → Claude writes the MCP connector into Claude Desktop and Claude Code with one click. Only the app can do this: the API runs in a container and has no home directory to write into. Details under MCP server.
-
Tray menu. Show window, fetch inbox, ports, backup, time widget on/off, activity on/off, stop containers, quit.
A menu item is handled once, by the handler on the builder. Tauri keeps one list of menu listeners for the whole app and calls every one of them for every event, wherever the menu sits, so a second handler on the tray icon would run each click twice — which for the two check marks is the difference between switching and not switching.
Tag a version and .github/workflows/release.yml builds the .dmg and
attaches it to the release — git tag v0.1.1 && git push --tags, or run the
workflow by hand with a tag as input.
The build is ad-hoc signed: there is no Developer-ID certificate in CI, so
macOS asks once. Right-click → Open on first launch, or take the download's
quarantine mark off with
xattr -d com.apple.quarantine /Applications/soloops.app. The release notes
say so too, because that is where somebody reads it.
A DMG opens as a Finder window, and by default that window is two icons on
grey with nothing explaining what to do with them. This one is drawn: the
word mark with its acid dot, an arrow from the app to the Applications
folder, what to do, and the sentence about the first launch — in raised,
the palette's colour for what lies on top of the work surface, which is also
the closest the palette gets to the white the app icon carries.
The picture is generated, not hand-drawn:
python3 apps/desktop/src-tauri/icons/dmg-background.pyIt writes icons/dmg-background.png at twice the size with 144 dpi, so the
Finder lays it out at 660×400 points with a Retina display's pixels. The icon
positions in that script and the ones in
tauri.conf.json have to agree —
the arrow is drawn into the gap between them.
One thing it cannot fix: icons/icon.icns has an opaque white background
rather than the transparent rounded square macOS expects, so the icon shows
as a white tile — in this window, and in the Dock and Launchpad too. The
window's colour was chosen to make that as quiet as possible.
The app is the frame around a stack that lives in a directory — the compose
file, the .env, data/. That path used to be baked in at build time, which
works for the machine that compiled it and for no other: an app built on a CI
runner would point at /Users/runner/work/…, and on the Mac that downloads it
nothing is behind that path.
So it looks, in this order (see
src/project.rs):
SOLOOPS_DIRfrom the environment — if somebody says so, that wins- the path remembered from a previous answer, under
~/Library/Application Support/com.philippniestroj.soloops/dir - the path baked in at build time, but only if it exists — the development build stays as convenient as it was
~/Desktop/PNSE/soloops,~/soloops,~/Developer/soloops,~/Projects/soloops- otherwise it asks once, with a folder dialog, and remembers the answer
A directory counts as the repository when it holds both a
docker-compose.yml and a package.json whose name is soloops. One mark
alone is any project with containers, or any npm project.
Building locally requires the Rust toolchain (rustup) and the Xcode command line tools.
The loaded interface gets as good as no access to Tauri APIs (see
capabilities/default.json):
it is the same web app as in the browser, just in a different frame. Menu, tray
and container startup run entirely in Rust.
The single exception is the Claude connection
(capabilities/claude.json):
there the interface may call exactly three commands — read the status, write the
connector, restart Claude Desktop. The commands are listed in
build.rs, because Tauri treats a page under
http://localhost as a remote origin and allows nothing there that no
capability names. Anything beyond those three stays with the menu and Rust.