feat(desktop): open threads from external links

[mrmg]

What Changed

• Adds the t3code://app/#/<environmentId>/<threadId> deep-link format (and t3code-dev in development).
• Validates links strictly so only a scoped T3 thread route is accepted; unrelated custom-scheme traffic, including Clerk callback paths, is ignored.
• Routes launch arguments, second-instance activations, and macOS open-url events through the same handler.
• Reuses an existing desktop window when available, or retains the requested route until the backend is ready during cold startup.
• Documents the URI for external tooling.

Why

External tools can now target the exact T3 Code conversation a user needs—for example external device control, an issue notification, or an email link—without relying on browser window behavior. The URL carries only environment and thread IDs; the desktop app still requires that environment to already be configured and authenticated.

Verification

• vp test run --config apps/desktop/vite.config.ts … — 38 focused tests passed.
• vp run --filter @t3tools/desktop build — passed.
• tsgo --noEmit in apps/desktop — passed (two pre-existing suggestions only).

Checklist

• This PR is small and focused
• I explained what changed and why
• No visual UI changes require screenshots
• No animation or interaction video is applicable

Built with GPT-5.6-terra in T3 Code.

---

Note

Medium Risk
Touches Electron startup ordering, multi-instance handling, and main-window load/navigation paths; links carry only IDs and do not bypass auth, but incorrect routing could strand or mis-navigate windows at cold start.

Overview
External tools can open a specific T3 Code thread in the desktop app via t3code://app/#/<environmentId>/<threadId> ( t3code-dev:// in dev). New DesktopDeepLink helpers build and strictly parse that route; unrelated custom-scheme URLs (e.g. Clerk callbacks) are rejected.

DesktopDeepLinkRouter wires the same path for process.argv, Electron second-instance, and buffered macOS open-url events ( makeEarlyOpenUrlBuffer on DesktopPreReadyPlatform, with pre-ready layer ordering adjusted in main.ts ). DesktopLifecycle configures the router at register time.

DesktopWindow.openThread navigates an existing window or defers until the backend is ready, serializes main-window creation, coalesces concurrent cold-start links to the latest thread, and tracks per-window URLs for same-origin navigation. User docs: docs/user/desktop-links.md.

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

Note

Add deep link support to open threads from external URLs in the desktop app

• Introduces t3code://app/#/<environmentId>/<threadId> as the deep link scheme for navigating to threads from external tools, with a separate t3code-dev scheme for development.
• Adds DesktopDeepLinkRouter to handle links from process.argv at startup, Electron second-instance events, and macOS open-url events.
• Buffers macOS open-url events that fire before Electron is ready, replaying them once a handler is registered.
• Extends DesktopWindow with openThread, which handles cold-start navigation to a thread URL, serializes concurrent window creation, and retries on development load failure.
• Documents the deep link format and behavior in docs/user/desktop-links.md.

^{Macroscope summarized 45c4b25.}

[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: c218e10b-6463-403f-be15-3510e27c613b

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 59f4eca. Configure here.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a new feature enabling external deep links to open threads in the desktop app. It adds new routing components, URL parsing, state management for pending URLs, and window lifecycle integration. New user-facing capabilities with this level of new logic warrant human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[t3dotgg]

Note

🤖 GPT-5.6 Sol responding on behalf of Theo

We're closing this PR as we clean up the T3 Code backlog. Thank you for taking the time to put this together.

We are keeping OPEN #8246 as the complete review path for desktop thread deep links. The focused lifecycle and routing tests here remain useful reference.

If you believe we closed this in error, please reopen the PR and leave a comment explaining what we missed.