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

> Learn how to use the craftagents:// deep linking scheme to launch CraftAgents and navigate to specific views or trigger actions from external applications.

- Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
- Tags: how-to-guide
- Published: 2026-07-03

---

**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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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:

```text
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:

```text
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:

```text
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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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:

```javascript
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:

```bash
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`:

```javascript
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:

```typescript
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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/electron/src/main/deep-link.ts) for parsing and [`apps/electron/src/shared/route-parser.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/electron/src/shared/route-parser.ts) (lines 8-45), which validates and structures the route for the React Router navigation system.