Skip to main content
Craft Agents supports deep linking via the craftagents:// URL protocol, allowing external applications and automation tools to navigate to specific views, create sessions, and trigger actions.

​
URL Protocol

All deep links use the custom protocol: 
craftagents://[workspace/{workspace-id}/]{route}
The workspace ID is optional. If omitted, the link uses the currently focused window.

​
URL Formats

Deep links support two primary formats:

​
Compound Routes (Hierarchical Navigation)

craftagents://allSessions[/session/{sessionId}]
craftagents://flagged[/session/{sessionId}]
craftagents://state/{stateId}[/session/{sessionId}]
craftagents://sources[/source/{sourceSlug}]
craftagents://settings[/{subpage}]
craftagents://skills[/skill/{skillId}]

​
Action Routes

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

​
Session Management

craftagents://allSessions

​
Settings Navigation

craftagents://settings

​
Source Management

craftagents://sources

​
Actions

Actions trigger specific operations within the application.

​
Create New Chat

Create a new chat session with optional pre-filled input: 
craftagents://action/new-chat
​
input
string
Pre-fill the chat input with this text
​
name
string
Set the session name (otherwise auto-generated)
​
send
boolean
If true and input is provided, immediately send the message

​
Session Actions

craftagents://action/resume-sdk-session/{sdk-session-id}

​
Workspace Targeting

Explicitly target a specific workspace by prefixing the route: 
craftagents://workspace/ws-123/allSessions/session/abc123

​
Window Management

Control how links open using query parameters:
​
window
enum
  • focused - Open in a new focused window
  • full - Open in a new full-screen window
craftagents://allSessions?window=focused
Open links with a specific right sidebar state:
​
sidebar
string
Right sidebar route (e.g., files/path/to/file, history)
craftagents://allSessions/session/abc123?sidebar=files/src/main.ts

​
Implementation Details

Deep link handling is implemented in apps/electron/src/main/deep-link.ts.

​
URL Parsing

The parseDeepLink() function parses URLs into structured targets: 
export interface DeepLinkTarget {
  /** Workspace ID - undefined means use active window */
  workspaceId?: string
  /** Compound route format (e.g., 'allSessions/session/abc123') */
  view?: string
  /** Action route (e.g., 'new-chat', 'delete-session') */
  action?: string
  actionParams?: Record<string, string>
  /** Window mode - if set, opens in a new window */
  windowMode?: 'focused' | 'full'
  /** Right sidebar param (e.g., 'files/path/to/file') */
  rightSidebar?: string
}
  1. Parse URL - Extract target workspace, route, and parameters
  2. Resolve Window - Get or create target window
  3. Wait for Ready - Ensure renderer is loaded (100ms delay after did-finish-load)
  4. Send IPC - Dispatch navigation via IPC_CHANNELS.DEEP_LINK_NAVIGATE
The 100ms delay after did-finish-load allows React to mount and register IPC listeners. This is necessary because did-finish-load fires when HTML is loaded, but before React’s useEffect hooks run.

​
Protocol Registration

The protocol is registered at app launch in the Electron main process: 
// Register as default protocol handler
if (process.defaultApp) {
  if (process.argv.length >= 2) {
    app.setAsDefaultProtocolClient('craftagents', process.execPath, [path.resolve(process.argv[1])])
  }
} else {
  app.setAsDefaultProtocolClient('craftagents')
}

​
Use Cases

​
Task Automation

Trigger agent sessions from task runners: 
# From a GitHub Action
open "craftagents://action/new-chat?input=Deploy%20to%20production&send=true"

# From a cron job
open "craftagents://action/new-chat?input=Daily%20standup%20summary&send=true"

​
IDE Integration

Create VS Code extension commands: 
vscode.commands.registerCommand('craft-agents.openSession', (sessionId) => {
  vscode.env.openExternal(vscode.Uri.parse(`craftagents://allSessions/session/${sessionId}`))
})

​
Browser Extensions

Navigate from web pages: 
// Open Craft Agents with selected text
const selectedText = window.getSelection().toString()
window.location.href = `craftagents://action/new-chat?input=${encodeURIComponent(selectedText)}`

​
OAuth Callbacks

Deep links with the auth-callback host are reserved for OAuth flows: 
craftagents://auth-callback?code=...&state=...
Auth callback URLs return null from parseDeepLink() and are handled by a separate OAuth handler.

Deep Link Handler

View the full implementation

IPC Channels

See IPC channel definitions

Build docs developers (and LLMs) love

Get started for freeTalk to us