Plugin SDK

Pivit ships with a plugin SDK so you can add your own commands to the command bar and the Pivit Wheel. A plugin is a TypeScript module that exports a set of commands; Pivit handles ranking, rendering and keyboard handling for you.

Everything in this section describes @pivit/api, the package plugins are written against.

What a plugin can do

• Run an action. A function command does something and closes — toggle a setting, open a URL, send a request.
• Show an interface. An interface command returns a React view rendered inside the command bar, using Pivit's own primitives.
• Rank itself against user input. Each command decides how relevant it is for what the user typed.
• Store settings. Declare a settings schema and Pivit renders the settings UI for you.

A minimal plugin

import { defineCommand, definePlugin, openUrl } from "@pivit/api";

export default definePlugin({
  commands: [
    defineCommand({
      id: "open-docs",
      name: "Open Pivit Docs",
      icon: "book-open",
      surfaces: { commandBar: true, wheel: true },
      execute: async () => {
        await openUrl("https://pivit.app/docs");
      }
    })
  ]
});

That is a complete, working plugin. It appears in the command bar, it appears on the Pivit Wheel, and it opens a URL.

Where to go next

• Getting started — project setup and loading a plugin locally
• Commands — function commands, interface commands and relevance scoring
• Building interfaces — the UI primitives available to plugin views
• Settings — declaring settings and reading them back

Requirements

Plugins are written in TypeScript and run inside Pivit on Windows 10 and 11. React 19 is a peer dependency for any plugin that renders an interface.