Skip to main content
Deeplinks are a navigation mechanism based on a custom URL that allows you to launch Qoder Desktop directly from a browser, documentation, terminal, or other external environment—opening a specific page or performing a specific action such as starting a chat, creating a Quest task, importing a rule, or adding an MCP service configuration. For Deeplinks that involve writing content or importing configurations, Qoder Desktop will display a confirmation dialog for you to review before proceeding. Some Deeplinks also require you to be logged in first. deeplink example

URL Format

{scheme}://{host}/{path}?{parameters}
ComponentDescriptionExample
schemeProtocolqoder
hostDeeplinks handler identifieraicoding.aicoding-deeplink
pathAction path/chat, /quest, /rule, /command, /mcp/add
parametersURL query parameterstext=hello&mode=agent
PathDescriptionLogin Required
/chatCreate ChatYes
/questCreate Quest taskYes
/ruleCreate ruleNo
/commandCreate custom commandNo
/mcp/addAdd MCP serviceNo

Create Chat /chat

Open a chat session directly via a link. When opening the link, Qoder Desktop will first show the content to be brought into the new conversation. After confirmation, it will create a new chat and pre-fill the text into the input box without sending it automatically. You must be logged in before using it.

URL Format

qoder://aicoding.aicoding-deeplink/chat?text={prompt}&mode={mode}&isNewChat={isNewChat}

Parameters

ParameterRequiredDescription
textYesThe prompt content to pre-fill
modeNoChat mode: agent, ask, chat, or experts when Experts is enabled. ask is handled as chat.
isNewChatNoWhether to create a new chat. Defaults to true; set to false to pre-fill the current chat.

Example

qoder://aicoding.aicoding-deeplink/chat?text=Help%20me%20refactor%20this%20code&mode=agent
function generateChatDeeplink(text: string, mode?: 'agent' | 'ask' | 'chat' | 'experts', isNewChat?: boolean): string {
  if (!text) {
    throw new Error('Missing required parameter: text');
  }

  const url = new URL('qoder://aicoding.aicoding-deeplink/chat');
  url.searchParams.set('text', text);
  if (mode) {
    url.searchParams.set('mode', mode);
  }
  if (isNewChat !== undefined) {
    url.searchParams.set('isNewChat', String(isNewChat));
  }

  return url.toString();
}

// Example
const deeplink = generateChatDeeplink('Help me refactor this code', 'agent');
console.log(deeplink);
// qoder://aicoding.aicoding-deeplink/chat?text=Help+me+refactor+this+code&mode=agent

Create Quest Task /quest

Open or focus the independent Quest window and pre-fill a new Quest draft. When opening the link, you can review the task description and execution mode before deciding whether to proceed. You must be logged in before using it.

URL Format

qoder://aicoding.aicoding-deeplink/quest?text={description}&agentClass={agentClass}

Parameters

ParameterRequiredDescription
textYesTask description
agentClassNoExecution mode: LocalAgent (default) or LocalWorktree

Execution Modes

ModeDescription
LocalAgentExecute in current workspace
LocalWorktreeExecute in isolated git worktree

Example

qoder://aicoding.aicoding-deeplink/quest?text=Implement%20user%20authentication%20with%20JWT&agentClass=LocalWorktree
type AgentClass = 'LocalAgent' | 'LocalWorktree';

function generateQuestDeeplink(text: string, agentClass?: AgentClass): string {
  if (!text) {
    throw new Error('Missing required parameter: text');
  }

  const url = new URL('qoder://aicoding.aicoding-deeplink/quest');
  url.searchParams.set('text', text);
  if (agentClass) {
    url.searchParams.set('agentClass', agentClass);
  }

  return url.toString();
}

// Example
const deeplink = generateQuestDeeplink('Implement user authentication with JWT', 'LocalWorktree');
console.log(deeplink);

Create Rule /rule

Import rules to guide AI behavior via a link. Rules can define coding standards, project conventions, or specific instructions for AI responses. When opening the link, you can first review the rule name and content before deciding whether to import it; upon confirmation, the corresponding rule will be created.

URL Format

qoder://aicoding.aicoding-deeplink/rule?name={ruleName}&text={ruleContent}

Parameters

ParameterRequiredDescription
nameYesRule name (used as filename)
textYesRule content

Example

qoder://aicoding.aicoding-deeplink/rule?name=typescript-conventions&text=Always%20use%20strict%20TypeScript%20types
function generateRuleDeeplink(name: string, text: string): string {
  if (!name || !text) {
    throw new Error('Missing required parameters: name and text');
  }

  const url = new URL('qoder://aicoding.aicoding-deeplink/rule');
  url.searchParams.set('name', name);
  url.searchParams.set('text', text);

  return url.toString();
}

// Example
const deeplink = generateRuleDeeplink(
  'typescript-conventions',
  `Always use strict TypeScript types.
Avoid using 'any' type.
Prefer interfaces over type aliases for object shapes.`
);
console.log(deeplink);

Add MCP Service /mcp/add

Quickly add MCP (Model Context Protocol) service configurations via a link. MCP services extend AI capabilities by providing additional tools and context sources. When opening the link, Qoder Desktop will first display the service information to be added and open the MCP settings page, allowing you to review and confirm simultaneously.

URL Format

qoder://aicoding.aicoding-deeplink/mcp/add?name={serverName}&config={base64EncodedConfig}

Parameters

ParameterRequiredDescription
nameYesMCP service name
configYesBase64 encoded MCP service JSON configuration
Note: The configuration must contain either command or url; if the name already exists, it cannot be added again.

Example

qoder://aicoding.aicoding-deeplink/mcp/add?name=postgres&config=JTdCJTIyY29tbWFuZCUyMiUzQSUyMm5weCUyMiUyQyUyMmFyZ3MlMjIlM0ElNUIlMjIteSUyMiUyQyUyMiU0MG1vZGVsY29udGV4dHByb3RvY29sJTJGc2VydmVyLXBvc3RncmVzJTIyJTJDJTIycG9zdGdyZXNxbCUzQSUyRiUyRmxvY2FsaG9zdCUyRm15ZGIlMjIlNUQlN0Q%3D
MCP service JSON configuration encoding Process:
  1. Create the configuration JSON object
  2. Serialize with JSON.stringify()
  3. URL encode with encodeURIComponent()
  4. Base64 encode with btoa()
  5. URL encode the result with encodeURIComponent()
interface McpServerConfig {
  command?: string;
  args?: string[];
  url?: string;
  env?: Record<string, string>;
}

function generateMcpAddDeeplink(name: string, config: McpServerConfig): string {
  if (!name) {
    throw new Error('Missing required parameter: name');
  }
  if (!config) {
    throw new Error('Missing required parameter: config');
  }
  if (!config.command && !config.url) {
    throw new Error('Config must contain either "command" or "url"');
  }

  const configJson = JSON.stringify(config);
  const base64Config = btoa(encodeURIComponent(configJson));
  const encodedName = encodeURIComponent(name);
  const encodedConfig = encodeURIComponent(base64Config);

  return `qoder://aicoding.aicoding-deeplink/mcp/add?name=${encodedName}&config=${encodedConfig}`;
}

// Example 1: PostgreSQL MCP Server
const postgresDeeplink = generateMcpAddDeeplink('postgres', {
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-postgres', 'postgresql://localhost/mydb']
});
console.log(postgresDeeplink);

// Example 2: GitHub MCP Server with environment variables
const githubDeeplink = generateMcpAddDeeplink('github', {
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-github'],
  env: { GITHUB_PERSONAL_ACCESS_TOKEN: '<YOUR_TOKEN>' }
});
console.log(githubDeeplink);

// Example 3: HTTP-based MCP Server
const httpDeeplink = generateMcpAddDeeplink('custom-server', {
  url: 'https://mcp.example.com/sse'
});
console.log(httpDeeplink);


Create Command /command

Quickly create custom commands via links, ideal for distributing common prompt templates, project operation guides, or team-agreed commands. When opening the link, Qoder Desktop will first display the command name, scope, description, and content before creating it upon confirmation.

URL Format

qoder://aicoding.aicoding-deeplink/command?name={name}&text={content}&description={description}&scope={scope}

Parameters

ParameterRequiredDescription
nameYesCommand name, must only contain lowercase letters, numbers, hyphens, and underscores
textYesCommand content
descriptionNoCommand description
scopeNoScope: user or project, default is user

Scope

ScopeDescription
userAdds only to the current user environment
projectAdds to the current workspace, suitable for team sharing

Example

qoder://aicoding.aicoding-deeplink/command?name=review_pr&text=Please%20help%20me%20review%20this%20PR&description=Review%20pull%20request&scope=user
type CommandScope = 'user' | 'project';

function generateCommandDeeplink(
  name: string,
  text: string,
  description?: string,
  scope: CommandScope = 'user'
): string {
  if (!name) {
    throw new Error('Missing required parameter: name');
  }
  if (!text) {
    throw new Error('Missing required parameter: text');
  }
  if (!/^[a-z0-9_-]+$/.test(name)) {
    throw new Error('Command name can only contain lowercase letters, numbers, hyphens and underscores');
  }

  const url = new URL('qoder://aicoding.aicoding-deeplink/command');
  url.searchParams.set('name', name);
  url.searchParams.set('text', text);
  if (description) {
    url.searchParams.set('description', description);
  }
  url.searchParams.set('scope', scope);

  return url.toString();
}

// Example
const deeplink = generateCommandDeeplink(
  'review_pr',
  'Please help me review this PR',
  'Review pull request'
);
console.log(deeplink);

Usage Notes

  1. After clicking the link, Qoder Desktop will first display the command information for your confirmation.
  2. name cannot be empty and can only use lowercase letters, numbers, hyphens, and underscores.
  3. scope=project requires you to have a workspace currently open; otherwise, it cannot be created.
  4. Commands with the same name cannot be created repeatedly.

Security Considerations

Important: Always review Deeplinks content before clicking.
  • Never include sensitive data: Do not embed API keys, passwords, or proprietary code in Deeplinks
  • Verify the source: Only click Deeplinks from trusted sources
  • Review before confirming: Qoder Desktop always shows a confirmation dialog - carefully review the content before proceeding
  • No automatic execution: Deeplinks never execute automatically; user confirmation is always required

Troubleshooting

IssuePossible CauseSolution
”Unregistered deeplink path”Unsupported deeplink pathCheck if the path is supported and ensure Qoder version is 0.2.21 or above
”Missing required parameter”Parameter not providedCheck that all required parameters are included in the URL
”Invalid JSON config”Malformed JSONValidate JSON structure before encoding
”Quest Mode is disabled”Quest feature not enabledEnable Quest Mode in Settings
Login prompt appearsDeeplink requires authenticationSign in to your account first
”Invalid Base64 encoded config”Incorrect MCP config encodingEnsure correct encoding order: JSON → encodeURIComponent → btoa → encodeURIComponent

URL Length Limits

Deeplink URLs should not exceed 8,000 characters. For longer content, consider:
  • Shortening the prompt or rule content
  • Using external references instead of inline content
  • Splitting into multiple deeplinks