[Feature]: Open a specific desktop thread via t3code://

[danyeah]

Before submitting

• I searched existing issues and did not find a duplicate.
• I am describing a concrete problem or use case, not just a vague idea.

Area

apps/desktop

Problem or use case

T3 Code already exposes thread deep links as /threads/<environmentId>/<threadId>, and the mobile app uses t3code://threads/<environmentId>/<threadId> for widgets and notification navigation.

On macOS, T3 Code is registered as the handler for the t3code scheme, but opening such a URL does not currently navigate the desktop app to the matching thread. The desktop app can be brought to the foreground, but the user still has to manually locate the conversation.

This prevents integrations such as a hardware controller, menu-bar status app, notification action, or other local automation from taking the user directly to the thread that needs attention.

Proposed solution

Support a documented desktop deep link for an existing thread:

t3code://threads/<environmentId>/<threadId>

When received, the desktop app should reveal/focus its main window and navigate through the existing typed renderer route:

/$environmentId/$threadId

With Electron's hash history this is represented as #/<environmentId>/<threadId> internally; the external/mobile contract can remain t3code://threads/....

The behavior should work when the app is already running and when it is launched through the link.

Why this matters

This brings desktop behavior in line with the existing mobile deep-link model and enables fast "attention -> exact conversation" workflows.

For example, I am building a small read-only MIDI controller integration: each pad represents a live T3 thread and its LED reflects its state. Pressing a pad can already focus T3 Code on macOS; opening the corresponding thread would make the interaction immediate and useful without relying on brittle GUI scripting or storing credentials.

Smallest useful scope

• Handle open-url on macOS.
• Handle the protocol URL passed to a second desktop instance on Windows/Linux.
• Parse only the t3code://threads/<environmentId>/<threadId> shape.
• Reveal the main window and forward the validated destination to the renderer.
• Navigate via the existing thread route after the renderer is ready.
• Ignore malformed or unsupported URLs safely.

No server API or authentication change is required.

Alternatives considered

• AppleScript/UI automation to search for and click a thread: fragile, locale-dependent, and requires Accessibility permission.
• Focusing the app only: this works today but still leaves the user to locate the correct chat.
• Opening the remote web UI: does not provide the native desktop workflow.

Risks or tradeoffs

The implementation needs to handle cold-start timing, duplicate URL events, and invalid or unavailable environment/thread IDs. The deep-link format should be treated as a stable public contract once documented.

The desktop renderer uses hash history, so the handoff should navigate through the renderer rather than assuming arbitrary external t3code:// URLs are already renderer routes.

Examples or references

• packages/shared/src/agentAwareness.ts builds /threads/<environmentId>/<threadId>.
• apps/mobile/src/widgets/AgentActivity.tsx turns that route into t3code://threads/<environmentId>/<threadId>.
• apps/web/src/main.tsx uses hash history under Electron.
• apps/desktop/src/app/DesktopClerk.ts already handles a second desktop instance by revealing the main window.
• Related: [Feature]: Deep link (t3code://checkout-pr) to open the PR-checkout dialog from outside the app #4625 proposes a different desktop deep-link (t3code://checkout-pr) and identifies the same missing external URL-routing layer.

Contribution

• I would be open to helping implement this.

[gsimone]

Want this to play around with the codex micro in a non-coupled way, left a comment in the PR. It would also be great to have t3code:// protocol links in chat, I'm always spawning threads with t3cli and it would be great to click around

[edwluo]

Opened an implementation of this in #6008.

It follows the shape described here: t3code://threads/<environmentId>/<threadId> externally, navigating through the existing /$environmentId/$threadId route internally. Works both when the app is already running (macOS open-url, Windows/Linux second-instance) and when the link is what launches it — in that case the target is held until the backend is ready rather than dropped.

Entirely up to the maintainers whether they want it; happy to shrink the scope if that helps.

[pjmuller]

+1 with a second concrete use case, plus a full list of the workarounds we tried so nobody repeats them (all dead ends).

Use case. A local skill fuzzy-finds a past thread (FTS over projection_thread_messages, then an agent narrows it down) and wants to hand the user a clickable link inside a T3 chat message that jumps the desktop app to that thread. Same need as @gsimone: agents/CLIs spawn many threads, we want to click around between them.

Tried on desktop 0.0.38, macOS, desktop-managed environment:

1. t3code://app only focuses the app. t3code://threads/<envId>/<threadId> and t3code://app/#/<envId>/<threadId> are no-ops: no open-url handler, DesktopClerk only reveals the window on second-instance.
2. Web client URL http://127.0.0.1:3773/<envId>/<threadId> works, but opens the default browser, lands on /pair (desktop-managed env), needs a t3 pair token, and then lives in Chrome rather than the desktop app.
3. Own scheme t3thread://<id> registered to a small macOS applet that focuses T3 Code and drives the command palette (Cmd+K, type title, Enter). Works when called from a shell (Accessibility granted to T3 Code), but the link is dead inside chat: ChatMarkdown.tsx sanitizes href to the rehype-sanitize defaults + file + t3-citation, and ElectronShell.parseSafeExternalUrl only forwards http(s)/remote-editor schemes. From a browser the applet additionally needs its own Automation (-1743) and Accessibility grants.
4. Launching Electron with --remote-debugging-port and setting location.hash over CDP: rejected, needs a relaunch flag baked into every launch and exposes full app control on localhost.
5. Patching app.asar: discarded, auto-update overwrites it.
6. Where we ended: no links at all; the user names the thread and an agent GUI-scripts the palette. Fragile (title collisions, archived threads are not in the palette, needs Accessibility).

Ask, two small pieces:

• (a) the desktop open-url handler for t3code://threads/<envId>/<threadId> as in feat(desktop): open a thread from a t3code:// deep link #6008;
• (b) allow t3code: in the chat markdown href whitelist and route it in-app (renderer navigates to /$environmentId/$threadId) instead of openExternal, so agents and CLIs can emit clickable thread links in chat.

Happy to test either.