Desktop app overview

The contributor desktop interfaces use the same source discovery, redaction, consent, receipt, and upload implementation as the CLI.

Current platform implementations

A SwiftUI menu-bar app for macOS, a GTK 4/libadwaita window for Linux, and a WinUI 3 window for Windows. The Linux window connects to the systemd-managed contributor daemon; the macOS and Windows apps host the daemon in-process.

All three carry the full path — enrol, preview, approve, receipt — so everything below under What the app can do applies to each of them. The Windows app is the newest and is still missing pieces at the edges: bulk withdrawal (a refusal rather than a gap — withdraw_bulk returns only counts, and the withdrawal contract forbids reporting a generic “withdrawn”, so withdraw per row instead), the watcher and connection sections of Settings, and most of the tray menu’s vocabulary.

Installing it

On macOS:

brew tap TraceCommons/tap
brew trust tracecommons/tap
brew install --cask trace-commons

brew trust is required — Homebrew refuses to load a formula or cask from a third-party tap without it.

Or take TraceCommons-0.3.0.dmg from the app-v0.3.0 release. It is a universal build, so it runs on both Apple silicon and Intel, and it is notarized and stapled — it opens without a Gatekeeper prompt even with no network. Use the app-v* tag rather than /releases/latest: the newest release overall is often a contributor-v* CLI one with no app in it.

On Windows:

Add-AppxPackage -AppInstallerFile https://storage.googleapis.com/tracecommons-flatpak/windows/TraceCommons.appinstaller

That installs the Authenticode-signed MSIX and leaves Windows to keep it current — it re-checks that address on launch, at most once every eight hours. The publisher shown at install time is CN=Iqlusion Inc; read it rather than clicking past it. If you would rather not install a package at all, trace-commons-app-windows-x86_64-0.3.0.zip unzips to a self-contained TraceCommons-0.3.0/TraceCommons.exe with the .NET runtime and Windows App SDK bundled in, and no update mechanism attached.

On Linux, as a flatpak:

flatpak install --from \
  https://storage.googleapis.com/tracecommons-flatpak/ai.tracecommons.Contributor.flatpakref

The OSTree repo behind that is GPG-signed and flatpak verifies it during install. The app is confined and asks for read-only access to ~/.claude/projects and ~/.codex/sessions and nothing wider — check for yourself with:

flatpak info --show-permissions ai.tracecommons.Contributor

If you point the daemon at a session directory outside those two, the confined app cannot read it; that is a real limitation of the flatpak rather than an oversight, and the CLI has no such restriction.

What the app can do

• Connect the local device to a Trace Commons instance.
• Show discovered projects without exposing full paths over the GUI socket.
• List pending sessions and their safe project labels.
• Generate and display the exact redacted envelope that an approval will send.
• Approve one item or a bounded batch.
• Ignore a project or explicitly arm it for automatic upload.
• Surface receipts, refusal reasons, daemon health, and local audit history.
• Sign in to the contributor’s account and withdraw previously submitted traces.

What the app never receives

• The device private key.
• A reusable raw upload claim.
• Full local project paths in daemon responses.
• Raw server error bodies that might contain sensitive values.

The Linux app connects through a user-protected Unix socket. The macOS app uses the same daemon contract through its in-process bridge. Project references cross the interface as opaque project_id values minted by the daemon, not full paths.

Project modes

Mode	Behavior
Ask / pending	New eligible sessions wait for review.
Ignore	Sessions from the project are not offered for upload.
Auto-upload	Future eligible sessions can upload under the standing policy after the app makes the armed state explicit.

Auto-upload is a durable opt-in. The app must keep armed projects visible and provide a direct way to disarm them.