# What Types of Contributions Can PI-Desktop Plugins Make?

> Discover the ten contribution types PI-Desktop plugins offer, from commands and panels to skills and themes. Extend PI-Desktop functionality with custom plugins.

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

---

**PI-Desktop plugins can extend the application through ten distinct contribution types—including commands, panels, agent tools, skills, themes, and background services—each configured in [`manifest.json`](https://github.com/vastsa/PI-Desktop/blob/main/manifest.json) and protected by the permission system defined in the `vastsa/PI-Desktop` repository.**

The `vastsa/PI-Desktop` plugin architecture uses a declarative manifest system that allows extensions to contribute capabilities ranging from UI components to AI agent functions. Understanding the available **PI-Desktop plugin contributions** is essential for developers who want to extend the application's functionality without modifying core code.

## How PI-Desktop Plugin Contributions Work

According to the `vastsa/PI-Desktop` source code, every contribution begins in the plugin's [`manifest.json`](https://github.com/vastsa/PI-Desktop/blob/main/manifest.json) file. The manifest declares what capabilities the plugin provides under the `contributes` key and what permissions it requires to operate safely. This declarative approach allows the host application to activate features lazily and enforce security boundaries before any code executes.

The definitive list of contribution types appears in [`docs/plugin-development.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/plugin-development.md) (lines 10–24), which maps each capability to its manifest key and core API methods.

## UI and Visual Contributions

Plugins can alter the user interface or add new interaction surfaces through four specific contribution types.

### Commands (Global Search Palette)

**Commands** provide explicit actions that users invoke through PI-Desktop's global search palette. To contribute a command, declare it in [`manifest.json`](https://github.com/vastsa/PI-Desktop/blob/main/manifest.json) under `contributes.commands`, then register it at runtime using `pi.commands.register` in your main entry point.

### Panels (Isolated HTML Windows)

**Panels** render isolated HTML UIs in separate windows. Contributors define the entry HTML in the `ui.panel` field of the manifest and request the `ui.panel` permission. The renderer process communicates with the host via `window.pluginBridge`, which proxies API calls across the Electron sandbox boundary.

### Work Panel Views (Docked Interfaces)

**Work panel views** integrate directly into the application's right-hand work panel rather than floating as separate windows. These are declared via `contributes.views` and require the `ui.view` permission. Like panels, they use `window.pluginBridge` for secure communication with the main process.

### Themes (Design Token Overrides)

**Themes** allow plugins to override the application's design tokens and change visual appearance without modifying core styles. Declare themes under `contributes.themes` and include the `ui.theme` permission in your manifest.

## AI Agent Contributions

PI-Desktop's integrated AI Agent can be extended through three specialized contribution types that enhance its reasoning and action capabilities.

### Agent Tools (Function Calling)

**Agent tools** are executable functions the AI invokes during conversation turns. Define the tool schema in [`manifest.json`](https://github.com/vastsa/PI-Desktop/blob/main/manifest.json) under `contributes.agentTools`, then implement the logic using `pi.agent.registerTool`. Each tool must specify a risk level (`low`, `medium`, or `high`) and JSON schema for arguments.

### Skills (Prompt Injection)

**Skills** provide prompt instructions that the Agent loads on demand to handle specific domains. These are markdown files listed under `contributes.skills` and require the `agent.prompt.inject` permission. Skills effectively extend the system prompt without hardcoding instructions into the core application.

### Reviewer Completions (Model Evaluation)

**Reviewer completions** enable one-shot host-owned tasks that run against the user's models to evaluate outputs or generate completions. Unlike other contribution types, these utilize runtime APIs—`pi.models.list`, `pi.session.getLlmContext`, and `pi.agent.complete`—rather than static manifest declarations, allowing dynamic interaction with the LLM context during execution.

## System and Integration Contributions

Beyond UI and AI extensions, plugins can contribute background processes and external integrations.

### Services (Background Processes)

**Services** are resident background tasks supervised by the host process. Declare them in `contributes.services` and request the `background.service` permission. Services run continuously while the plugin is active, making them suitable for synchronization tasks or persistent connections.

### MCP Servers (External Tool Discovery)

**MCP servers** integrate tools discovered from local or remote Model Context Protocol servers. Contributors declare these under `contributes.mcpServers` with appropriate MCP permissions, allowing PI-Desktop to consume tools exposed by external MCP-compatible endpoints.

### Message Bus (Event Publishing)

**Message bus** contributions enable typed event publishing and subscribing between plugins and the host. Declared under `contributes.bus`, this capability allows loosely coupled communication using conventions rather than direct API calls.

## Practical Implementation: Multi-Capability Plugin

The `examples/plugins/hello/` directory in the `vastsa/PI-Desktop` repository demonstrates a plugin combining commands, panels, agent tools, and skills. Below is the complete implementation structure.

### Manifest Declaration

The [`manifest.json`](https://github.com/vastsa/PI-Desktop/blob/main/manifest.json) file declares multiple contribution types simultaneously:

```json
{
  "schemaVersion": 1,
  "id": "local.my-awesome-plugin",
  "name": "My Awesome Plugin",
  "version": "0.1.0",
  "description": "Shows a panel and provides an agent tool.",
  "main": "main.js",
  "ui": {
    "panel": "renderer/index.html",
    "title": "Awesome Panel",
    "width": 500,
    "height": 400
  },
  "contributes": {
    "commands": [
      {
        "id": "my-awesome-plugin.open",
        "title": "Open Awesome Panel",
        "keywords": ["awesome", "panel"]
      }
    ],
    "agentTools": [
      {
        "name": "reverse_text",
        "description": "Reverse a string.",
        "risk": "low",
        "schema": {
          "type": "object",
          "properties": { "text": { "type": "string" } },
          "required": ["text"]
        }
      }
    ],
    "skills": ["skills/reverse.md"]
  },
  "permissions": ["ui.panel", "agent.tool.register", "agent.prompt.inject"],
  "engines": { "piDesktop": ">=0.1.0" },
  "activationEvents": [
    "onCommand:my-awesome-plugin.open",
    "onStartup"
  ]
}

```

### Main Process Registration

The [`main.js`](https://github.com/vastsa/PI-Desktop/blob/main/main.js) entry point registers runtime handlers that connect manifest declarations to functional code:

```javascript
async function onLoad() {
  // Register the command that opens the panel
  await pi.commands.register({
    id: "my-awesome-plugin.open",
    title: "Open Awesome Panel",
    run: async () => {
      await pi.ui.openPanel({ title: "Awesome Panel" });
      await pi.ui.showToast("Panel opened!");
    },
  });

  // Register the agent tool that reverses text
  await pi.agent.registerTool({
    name: "reverse_text",
    description: "Reverse a string.",
    risk: "low",
    schema": {
      type: "object",
      properties: { text: { type": "string" } },
      required: ["text"],
    },
    execute: async (args) => ({
      reversed: String(args.text).split("").reverse().join(""),
    }),
  });
}

async function onUnload() {
  await pi.commands.unregister("my-awesome-plugin.open");
  await pi.agent.unregisterTool("reverse_text");
}

module.exports = { onLoad, onUnload };

```

### Panel Renderer

The panel UI ([`renderer/index.html`](https://github.com/vastsa/PI-Desktop/blob/main/renderer/index.html)) runs in a sandboxed Electron window without Node integration, communicating via `window.pluginBridge`:

```html
<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Awesome Panel</title>
</head>
<body>
  <h1>Hello from Awesome Plugin!</h1>
  <button id="toast">Show Toast</button>

  <script>
    document.getElementById("toast").addEventListener("click", async () => {
      await window.pluginBridge.invoke("ui.showToast", {
        message: "You clicked the button!"
      });
    });
  </script>
</body>
</html>

```

### Skill Definition

Skills are markdown files with frontmatter that the Agent loads when relevant:

```markdown
---
name: Reverse Text
description: Reverse a string supplied by the user.
---

The user may ask: "Please reverse the phrase **«text»**."
When invoked, use the `reverse_text` tool to return the reversed string.

```

## Summary

- **Ten contribution types** are available in PI-Desktop: Commands, Panels, Work Panel Views, Agent Tools, Reviewer Completions, Skills, Themes, MCP Servers, Services, and Message Bus (as documented in [`docs/plugin-development.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/plugin-development.md) lines 10–24).
- **Declarative configuration** via [`manifest.json`](https://github.com/vastsa/PI-Desktop/blob/main/manifest.json) under the `contributes` field defines what capabilities a plugin provides, while the `permissions` array enforces security boundaries.
- **UI contributions** (Commands, Panels, Views, Themes) extend the visual interface, with Panels and Views utilizing `window.pluginBridge` for secure cross-process communication.
- **AI contributions** (Agent Tools, Skills, Reviewer Completions) enhance the built-in Agent through function calling, prompt injection, and direct LLM context access.
- **System contributions** (Services, MCP Servers, Message Bus) enable background processing, external tool integration, and event-driven architecture.

## Frequently Asked Questions

### Can a single PI-Desktop plugin contribute multiple capability types?

Yes. A single plugin can combine any subset of contribution types. The example in `examples/plugins/hello/` demonstrates a plugin contributing Commands, Agent Tools, and Skills simultaneously, all declared within the same [`manifest.json`](https://github.com/vastsa/PI-Desktop/blob/main/manifest.json) and implemented in a shared [`main.js`](https://github.com/vastsa/PI-Desktop/blob/main/main.js) entry point.

### What permissions are required for AI agent tool contributions?

PI-Desktop requires explicit user consent through the `agent.tool.register` permission to register agent tools, and `agent.prompt.inject` to contribute skills. Additionally, tools must declare a risk level (`low`, `medium`, or `high`) in their schema definition to inform the consent system.

### How do themes differ from panels in PI-Desktop plugins?

**Themes** contribute design token overrides that change the global appearance of the application without adding new UI elements, while **Panels** are complete HTML interfaces displayed in separate, sandboxed windows. Themes use the `contributes.themes` manifest key and `ui.theme` permission, whereas Panels use the `ui.panel` configuration block and `ui.panel` permission.

### Where is the complete plugin manifest schema documented?

The full JSON schema for [`manifest.json`](https://github.com/vastsa/PI-Desktop/blob/main/manifest.json) is defined in [`spec/07-plugins/02-plugin-manifest-schema.md`](https://github.com/vastsa/PI-Desktop/blob/main/spec/07-plugins/02-plugin-manifest-schema.md), while the complete permission matrix mapping each contribution type to required permissions appears in [`spec/07-plugins/13-plugin-permissions-matrix.md`](https://github.com/vastsa/PI-Desktop/blob/main/spec/07-plugins/13-plugin-permissions-matrix.md). The high-level architecture overview is available in [`spec/07-plugins/01-plugin-system.md`](https://github.com/vastsa/PI-Desktop/blob/main/spec/07-plugins/01-plugin-system.md).