How Built-In Tools Are Executed in PI-Desktop: A Complete Technical Guide

Built-in tools in PI-Desktop are executed through a static declaration system where commands are defined in builtin-commands.ts, exposed via helper functions, and dispatched by the main Electron process based on a source: "builtin" marker.

PI-Desktop is an Electron-based application that ships with core functionality provided by first-party built-in tools. These tools are executed through a deterministic pipeline that ensures core features remain available regardless of third-party plugin states. Understanding how built-in tools are executed within PI-Desktop reveals a static data approach that prioritizes reliability and version control.

Static Declaration of Built-In Commands

All built-in commands are defined as static data structures in apps/desktop/electron/main/builtin-commands.ts. This file exports the BUILTIN_COMMANDS array, which contains the canonical definitions for every core feature.

Each command entry includes an id, human-readable title, category, searchable keywords, a source: "builtin" marker, and a unique slash alias for Composer integration:

export const BUILTIN_COMMANDS: BuiltinCommandDef[] = [
  { id: "builtin.session.new", title: "New task", …, source: "builtin", slash: "new" },
  { id: "builtin.agent.compact", title: "Compact …", …, source: "builtin", slash: "compact" },
  // …other built‑ins
];

This static approach ensures that built-in tools are versioned with the application and loaded at runtime without external dependencies.

Exposing Commands to the UI Layer

The raw command definitions are transformed for consumption by different UI components through specific helper functions that strip or remap fields according to context.

Command Palette Integration

The builtinPaletteItems() function processes BUILTIN_COMMANDS to remove the UI-specific slash field, returning a clean CommandItem[] array for the palette interface:

export function builtinPaletteItems(): CommandItem[] {
  return BUILTIN_COMMANDS.map(({ slash: _slash, …item }) => item);
}

Composer Slash Commands

For the Composer "/" menu, builtinComposerCommands() converts each definition into a ComposerCommand structure where the kind is fixed to "builtin" and the name field maps to the slash alias:

export function builtinComposerCommands(): ComposerCommand[] {
  return BUILTIN_COMMANDS.map(def => ({
    name: def.slash,
    kind: "builtin",
    title: def.title,
    id: def.id,
    ...(def.category ? { description: def.category } : {})
  }));
}

When a user types "/new", the dispatcher resolves this to the id "builtin.session.new" through this mapping.

Built-In Skills Execution Pipeline

Beyond simple commands, PI-Desktop supports built-in skills that provide markdown-based instructions to the language model. These are managed in apps/desktop/electron/main/builtin-skills.ts.

The builtinSkills(input) function checks workspace context (such as isPluginWorkspace for plugin development) and returns available skills based on front-matter parsed from markdown files. When the model requests a skill body, loadBuiltinSkillBody(id) retrieves the specific content:

import { loadBuiltinSkillBody } from "@pi-desktop/electron/main/builtin-skills";

const skill = loadBuiltinSkillBody("pi-desktop/plugin-development");
if (skill) {
  // skill.body contains the markdown the model will execute
}

Built-in skills execute without requiring external permission grants, as they are part of the core application bundle.

Command Dispatch and Runtime Execution

Execution begins when UI components send command IDs over IPC to the main process defined in apps/desktop/src/lib/commands.ts. The dispatcher matches the incoming id against the lists returned by builtinPaletteItems() or builtinComposerCommands().

Because each built-in command carries source: "builtin", the dispatcher routes the request to internal handlers rather than plugin extensions. Typical execution paths include:

• builtin.session.new → Creates a fresh chat session
• builtin.agent.compact → Invokes runtime context-compaction logic
• builtin.mode.* → Toggles UI modes (Agent / Plan / Goal)

For skill execution, the runtime in packages/agent-runtime/src/runtime.ts maintains a merged catalog of builtinSkills, plugin skills, and user skills. When the model issues a Skill tool call, the runtime checks this catalog; if the ID matches a built-in skill, the system calls loadBuiltinSkillBody to provide the markdown instructions directly.

Summary

• Built-in tools are declared statically in builtin-commands.ts with unique IDs, titles, and slash aliases
• Helper functions (builtinPaletteItems, builtinComposerCommands) transform raw definitions for specific UI contexts
• The main process dispatcher in commands.ts routes execution based on the source: "builtin" marker
• Built-in skills are resolved at runtime through builtin-skills.ts without requiring external permissions
• This architecture ensures core functionality remains versioned, isolated, and always available regardless of third-party plugin states

Frequently Asked Questions

What file defines the built-in commands in PI-Desktop?

The canonical list lives in apps/desktop/electron/main/builtin-commands.ts, which exports the BUILTIN_COMMANDS array containing all command IDs, titles, categories, and slash aliases.

How does PI-Desktop differentiate between built-in and plugin commands?

Each built-in command includes a source: "builtin" marker in its definition. The dispatcher in apps/desktop/src/lib/commands.ts checks this field to route requests to internal handlers rather than plugin extension points.

Can built-in skills access the filesystem like plugin skills?

Yes, built-in skills execute with full application privileges. Unlike plugin skills that may require permission grants, built-in skills defined in builtin-skills.ts can read workspace files directly through the Electron main process when validating contexts like isPluginWorkspace.

Where is the command dispatch logic located?

The primary dispatch logic resides in apps/desktop/src/lib/commands.ts for UI-initiated commands, while skill-specific execution is handled by packages/agent-runtime/src/runtime.ts, which merges built-in, plugin, and user skill catalogs before executing Skill tool calls.

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