fix(desktop): claim the t3code:// scheme default on Linux at startup

[juliusmarminge]

Summary

Follow-up to #5015. Linux users still get the "Choose an application to open 't3code'" prompt on every OAuth callback (and Firefox flows keep failing), even though the scheme registration from #5015 shipped — the app now appears in the chooser but is never recorded as the default handler for x-scheme-handler/t3code.

Why the OS keeps prompting

Linux ships as an AppImage, so the integrated .desktop entry's filename is decided by whatever integration tool the user runs (AppImageLauncher names it appimagekit_<hash>-….desktop). Electron's app.setAsDefaultProtocolClient resolves the desktop id from setDesktopName (t3code.desktop), which can never match those files — so there is no reliable built-in way to claim the default.

The fix

On packaged Linux startup, the new DesktopLinuxUrlHandler service:

1. Writes a dedicated t3code-url-handler.desktop into $XDG_DATA_HOME/applications (default ~/.local/share/applications) with Exec="$APPIMAGE" %U, MimeType=x-scheme-handler/t3code;, and NoDisplay=true. Pointing at $APPIMAGE matters: process.execPath lives in the transient /tmp/.mount_* squashfs (it is used only as a fallback outside an AppImage). Exec values use freedesktop quoting (% doubled, " ` $ \ escaped).
2. Claims the scheme default via xdg-mime default t3code-url-handler.desktop x-scheme-handler/t3code — the same association the file manager's "set as default app" checkbox records in mimeapps.list.

Registration is best-effort: any failure (missing xdg-utils, read-only home) logs a warning and never blocks startup; the OS chooser remains as fallback. Re-running on every launch keeps the Exec path current when the AppImage moves, and lets whichever channel (stable/nightly) launched last own the scheme — matching macOS semantics.

Supporting changes: DesktopConfig reads XDG_DATA_HOME, and DesktopEnvironment exposes linuxApplicationsDir + appImagePath (already parsed from $APPIMAGE).

User impact

After updating and launching the app once, browser OAuth redirects open T3 Code directly — no chooser dialog in Chrome/Chromium, and Firefox shows its standard one-time confirmation with T3 Code preselected instead of failing.

Test plan

• New DesktopLinuxUrlHandler.test.ts: desktop-entry rendering incl. Exec quoting, AppImage vs. executable fallback, xdg-mime invocation, platform/packaged gating, and that write/xdg-mime failures never fail startup
• Full desktop suite passes (411 tests), typecheck clean

🤖 Generated with Claude Code

---

Note

Low Risk
Linux-only, packaged-only startup side effect with failures logged and startup never blocked; writes one user desktop file and runs xdg-mime.

Overview
Packaged Linux builds now register t3code:// as the default URL handler at startup so OAuth callbacks do not keep opening the system “choose an application” dialog.

A new DesktopLinuxUrlHandler service writes a hidden t3code-url-handler.desktop under $XDG_DATA_HOME/applications (from XDG_DATA_HOME, default ~/.local/share/applications) with MimeType=x-scheme-handler/t3code;, Exec pointing at $APPIMAGE when set (not the transient AppImage mount path), then runs xdg-mime default to claim the scheme. Registration is best-effort (warnings only) and is skipped on non-Linux or unpackaged runs. DesktopApp startup invokes linuxUrlHandler.register after whenReady.

^{Reviewed by Cursor Bugbot for commit 76e80dd. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Claim the t3code:// URL scheme default on Linux at app startup

• Adds DesktopLinuxUrlHandler.ts, a new service that writes a freedesktop .desktop entry file and invokes xdg-mime default to register the app as the default handler for the t3code:// scheme.
• Reads XDG_DATA_HOME from the environment (falling back to ~/.local/share) to determine where to write the .desktop file, exposed via DesktopEnvironment.
• Registration runs only on Linux packaged (AppImage) builds; non-Linux and unpackaged builds are no-ops.
• Failures during registration are captured in a structured DesktopLinuxUrlHandlerRegistrationError and logged without crashing startup.

^{Macroscope summarized 76e80dd.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6fdbad26-1085-4cba-a3cd-0bfcdda20f6f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Reviewed the new DesktopLinuxUrlHandler service against the Effect service conventions. The service/tag/make/layer shape, namespace imports, dependency acquisition (yield* Foo.Foo), and Effect.catch on a fully-handled channel all look right. Two error-modeling issues below.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a new Linux-specific feature that writes .desktop files and executes xdg-mime commands at startup to claim URL scheme defaults. While well-scoped and defensive (failures don't block startup), new features with filesystem/process interactions warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}