How to Use the craftagents:// Deep Linking Scheme for Navigation in CraftAgents

The craftagents:// protocol enables external applications to launch the CraftAgents desktop client and navigate to specific UI views or trigger actions through structured compound routes, action commands, and optional workspace targeting.

CraftAgents OSS implements a custom URL protocol that transforms external links into precise navigation commands within the Electron-based desktop application. This deep linking scheme allows browsers, CLI tools, and third-party apps to open specific sessions, create new chats, or manage workspaces programmatically. Understanding the craftagents:// format is essential for integrating external workflows with the CraftAgents ecosystem.

URL Structure and Route Types

The deep linking system recognizes two primary route categories defined in apps/electron/src/main/deep-link.ts (lines 8-15). Each URL follows a strict hierarchy that determines whether the app performs navigation or executes a command.

Compound Routes for UI Navigation

Compound routes map directly to the application's navigator hierarchy, encoding both the view location and optional filters or detail selections. The format follows:

craftagents://{compoundRoute}[?window=focused|full&sidebar=...]

Common patterns include:

• craftagents://allSessions – Opens the Sessions navigator with the All Sessions filter
• craftagents://allSessions/session/abc123 – Same navigator with session card abc123 selected
• craftagents://sources/source/github – Sources navigator with the github source detail view open
• craftagents://settings/shortcuts – Settings page focused on the Shortcuts sub-page

Action Routes for Immediate Commands

Action routes trigger specific operations rather than navigation, such as creating sessions or deleting records. These URLs follow the pattern:

craftagents://action/{actionName}[/{id}][?params]

For example:

• craftagents://action/new-chat?input=Hello&send=true – Creates a new chat and immediately sends the message "Hello"
• craftagents://action/delete-session/abc123 – Permanently removes session abc123
• craftagents://action/resume-sdk-session/42 – Resumes a Claude-Code SDK session with ID 42

Workspace Targeting and Display Modes

You can scope any deep link to a specific workspace window using the workspace host segment:

craftagents://workspace/{workspaceId}/{compoundRoute}

Query parameters control the window behavior:

• window=focused – Opens a new focused window instead of reusing the active one
• window=full – Launches in full-screen mode
• sidebar={tab} – Opens a specific right-sidebar tab upon navigation

Implementation Architecture

The deep linking mechanism relies on a three-stage pipeline that processes URLs from the operating system through to the React Router.

Main Process Parsing in deep-link.ts

The Electron main process registers the protocol via app.setAsDefaultProtocolClient('craftagents'). When the OS receives a matching URL, the parseDeepLink() function (defined in apps/electron/src/main/deep-link.ts lines 95-124) extracts:

• Workspace ID – If the URL starts with craftagents://workspace/{id}
• Route type – Distinguishes between compound navigation and action execution
• Window mode – Determines if the target should open in a focused or full window
• Action parameters – Query string values passed to action handlers

Route Resolution in route-parser.ts

For compound routes, the renderer process receives a DeepLinkNavigation object via IPC. The type-safe routing system in apps/electron/src/shared/route-parser.ts (lines 8-45) converts the string path into a structured navigation state that React Router consumes. This ensures that parameters like session IDs or source filters are validated before the UI updates.

Action routes bypass the navigator and instead invoke RPC methods through RPC_CHANNELS.DEEPLINK, calling server APIs such as deleteSession or resumeSdkSession directly.

Practical craftagents:// Deep Link Examples

Opening a Specific Session from Node.js

Use the open command (macOS) or equivalent to launch a session view:

import { exec } from 'child_process';

// Opens session abc123 in the default CraftAgents window
exec('open "craftagents://allSessions/session/abc123"');

Creating a New Chat with Pre-filled Input

From a bash script, trigger a new chat and send an initial message immediately:

open "craftagents://action/new-chat?input=Hello%20world&send=true"

Targeting a Workspace with Focused Window

Open a specific source in a new focused window within workspace ws7:

window.electronAPI.openUrl(
  'craftagents://workspace/ws7/sources/source/github?window=focused'
);

Building OAuth Callback URLs

The SDK provides helpers to construct valid deep links for authentication flows:

import { buildOAuthDeeplinkUrl } from '@craft-agents/shared/auth';

const deepLink = buildOAuthDeeplinkUrl({
  workspaceId: 'ws123',
  afterLoginRoute: 'allSessions',
});
// Returns: craftagents://workspace/ws123/allSessions
window.location.href = deepLink;

This helper is tested in packages/shared/src/auth/__tests__/exports-and-session-context.test.ts.

Summary

• The craftagents:// protocol enables external applications to control the CraftAgents desktop client through custom URLs.
• Compound routes (e.g., allSessions/session/abc123) navigate to specific UI views with optional filters.
• Action routes (e.g., action/new-chat) trigger immediate commands like creating chats or deleting sessions.
• Workspace targeting prefixes any route with workspace/{id}/ to control which window receives the navigation.
• Key implementation files include apps/electron/src/main/deep-link.ts for parsing and apps/electron/src/shared/route-parser.ts for type-safe route resolution.

Frequently Asked Questions

How do I open a CraftAgents session from a browser bookmark?

Create a bookmark with the URL craftagents://allSessions/session/YOUR_SESSION_ID. When clicked, the browser delegates to the CraftAgents application, which parses the compound route in deep-link.ts and navigates to the specified session card. Ensure the CraftAgents desktop client is installed and the craftagents protocol handler is registered with your operating system.

What is the difference between compound routes and action routes?

Compound routes navigate the UI hierarchy (e.g., sources/source/github opens the sources navigator with the GitHub source selected), while action routes execute commands without changing the navigator view (e.g., action/delete-session/abc123 triggers deletion via RPC). Action routes are processed immediately by the main process, whereas compound routes generate a DeepLinkNavigation object sent to the renderer for React Router handling.

Can I specify which window or workspace receives the deep link?

Yes. Append ?window=focused to open a new dedicated window, or prepend workspace/{workspaceId}/ to target a specific workspace instance. For example, craftagents://workspace/ws42/action/new-chat?window=focused creates a new chat in workspace ws42 within a fresh focused window rather than the active tab.

Where does the URL parsing logic reside in the codebase?

The primary parsing logic lives in apps/electron/src/main/deep-link.ts within the parseDeepLink() function (lines 95-124). This extracts the workspace ID, route type, and query parameters. The renderer-side type conversion occurs in apps/electron/src/shared/route-parser.ts (lines 8-45), which validates and structures the route for the React Router navigation system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}