Set up a Pivit plugin project, write your first command, and load it into Pivit for local development.

This page takes you from an empty folder to a command running inside Pivit.

Create a project

mkdir my-pivit-plugin
cd my-pivit-plugin
npm init -y
npm install @pivit/api
npm install -D typescript @types/react

Plugins that render an interface also need React 19 available, since @pivit/api declares it as a peer dependency.

Configure TypeScript

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "skipLibCheck": true
  }
}

Write the plugin

A plugin's default export is the result of definePlugin. The only required field is commands.

src/index.tsx

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

export default definePlugin({
  commands: [
    defineCommand({
      id: "hello",
      name: "Say Hello",
      icon: "hand",
      execute: async () => {
        await showToast({ title: "Hello from my plugin" });
      }
    })
  ]
});

Each command needs three things:

Field	Purpose
`id`	Stable identifier, unique within the plugin
`name`	What the user sees in the command bar
`icon`	An icon name from Pivit's icon set

Choose where the command appears

surfaces controls which parts of Pivit list the command. Commands appear in the command bar by default and stay off the wheel unless you ask for it.

surfaces: { commandBar: true, wheel: true }

Reserve the wheel for commands worth a gesture — things you run constantly. A wheel crowded with rarely used commands is slower than typing.

Load it into Pivit

Build your plugin, then add it as a local plugin from Pivit's plugin settings. Pivit reloads local plugins when their output changes, so a watch build gives you a reasonable development loop:

npx tsc --watch

Use Log from @pivit/api rather than console so your output lands in Pivit's log stream:

import { Log } from "@pivit/api";

Log.info("Plugin loaded", { commands: 1 });

Next steps

Once the command runs, the interesting part is relevance scoring — deciding when your command should appear and how highly it should rank.

Getting started