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

> Learn how built-in tools execute in PI-Desktop with this technical guide. Discover the static declaration system and command dispatch process via Electron.

- Repository: [Lan/PI-Desktop](https://github.com/vastsa/PI-Desktop)
- Tags: how-to-guide
- Published: 2026-09-11

---

**Built-in tools in PI-Desktop are executed through a static declaration system where commands are defined in [`builtin-commands.ts`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/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:

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

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

```typescript
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`](https://github.com/vastsa/PI-Desktop/blob/main/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:

```typescript
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`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/commands.ts) routes execution based on the `source: "builtin"` marker
- Built-in skills are **resolved at runtime** through [`builtin-skills.ts`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/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`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/src/lib/commands.ts)** for UI-initiated commands, while skill-specific execution is handled by **[`packages/agent-runtime/src/runtime.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/agent-runtime/src/runtime.ts)**, which merges built-in, plugin, and user skill catalogs before executing `Skill` tool calls.