Deep Links in ToolHive Studio

Deep links allow external systems (browsers, terminals, other apps) to trigger navigation inside ToolHive Desktop via the toolhive-gui:// custom protocol.

About this document: Much of the content in the reference docs is the result of research into how other Electron apps implement deep links. Some design decisions are implemented; others describe the intended direction but are not yet in the codebase. The base skill reflects the current implementation. The reference docs reflect the research and design intent — read them with that in mind, and update them when relevant implementation decisions change.

URL Schema

toolhive-gui://v1/<intent>[?<query>]

Examples:

• toolhive-gui://v1/open-registry-server-detail?serverName=fetch — open a registry server detail page

The v1 segment is the version. The intent is a kebab-case action name. Query params carry intent-specific data.

Current Implementation

Key Files

IPC Channel

deep-link-navigation — sent main → renderer as a NavigateTarget ({ to: string; params?: Record<string, string> }).

The renderer receives this and calls the TanStack Router navigate() directly.

How It Works (Current)

1. Protocol registration: On app start, app.setAsDefaultProtocolClient('toolhive-gui') registers the protocol. On Windows with Squirrel, registerProtocolWithSquirrel() is called instead (see squirrel.ts).
2. URL extraction: On Windows/Linux, the URL arrives in process.argv. extractDeepLinkFromArgs() scans for the first toolhive-gui:// argument (safe against argv injection — see patterns doc).
3. Parse + validate: parseDeepLinkUrl() parses the URL and runs it through the Zod discriminated union schema defined in common/deep-links.ts. Invalid links resolve to showNotFound.
4. Window ready: waitForMainWindowReady() polls until the window is visible and not loading before dispatching.
5. Dispatch: resolveDeepLinkTarget() converts the validated intent to a NavigateTarget, which is sent to the renderer via the deep-link-navigation IPC channel.
6. Renderer: The renderer listens for deep-link-navigation and calls navigate(target).

Current Limitations vs. Design Intent

The current implementation only supports read (navigate) operations. The design doc proposes a confirmation flow for write/destructive operations (C/U/D), but this is not yet implemented. The IPC sends a pre-resolved NavigateTarget rather than a raw parsed intent — this simplified the initial implementation. See design doc for the full intended model.

How to Add a New Deep Link

All changes happen in common/deep-links.ts:

ts
1// 1. Define the new intent using v1DeepLink()
2export const myNewIntent = v1DeepLink({
3  intent: 'my-new-intent', // kebab-case, matches URL path segment
4  params: z.object({
5    someParam: safeIdentifier, // use safeIdentifier for user-supplied strings
6  }),
7  navigate: (params) => ({
8    to: '/some-route/$id', // TanStack Router route
9    params: { id: params.someParam },
10  }),
11})
12
13// 2. Add to allDeepLinks array
14const allDeepLinks = [
15  openRegistryServerDetail,
16  showNotFound,
17  myNewIntent,
18] as const
19
20// 3. Add to deepLinkSchema discriminated union
21export const deepLinkSchema = z.discriminatedUnion('intent', [
22  openRegistryServerDetail.schema,
23  showNotFound.schema,
24  myNewIntent.schema, // ← add here
25])

Test manually:

bash
1./node_modules/.bin/electron . "toolhive-gui://v1/my-new-intent?someParam=value"

safeIdentifier is defined as z.string().regex(/^[a-zA-Z0-9_.-]+$/) — use it for any param that could be user-supplied to prevent injection.

Reference Documents

For deeper background, see:

• OS & Packaging Support — Platform-specific registration requirements (Windows, Linux, macOS) and packaging format considerations (Squirrel, Flatpak, .deb, .rpm, .dmg, AppImage, MSIX, etc.). Largely research/prior art.
• Observed Patterns — Patterns from VS Code, GitHub Desktop, Mattermost, Element, and others: URL sanitization, argv injection, security confirmations, waiting-for-readiness patterns, telemetry.
• Design & Decisions — Full design rationale, IPC model, error handling strategy, queue management, testing approach, and the decisions log. Some sections describe planned future behaviour not yet implemented.