What Types of Contributions Can PI-Desktop Plugins Make?

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 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 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 (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 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 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 file declares multiple contribution types simultaneously:

{
  "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 entry point registers runtime handlers that connect manifest declarations to functional code:

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) runs in a sandboxed Electron window without Node integration, communicating via window.pluginBridge:

<!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:

---
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 lines 10–24).
• Declarative configuration via 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 and implemented in a shared 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 is defined in 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. The high-level architecture overview is available in spec/07-plugins/01-plugin-system.md.

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