Guide · Introduction
Plugin author's guide
Petty's behavior is powered entirely by JavaScript plugins running in a sandboxed JSContext. Every personality trait, integration, notification, and quip you see comes from a plugin. This guide shows you how to build your own.
What's a plugin?
A plugin is a folder with two files: manifest.json and a JavaScript entry point. The manifest declares an id, the capabilities it plays (quips, reactions, watchers, menu items, file actions, TTS provider) and the permissions it needs (calendar, network, exec, …). The JavaScript runs against the petty.* API, which is injected into the sandbox based on those manifest declarations.
Every built-in behavior (pomodoro, git, calendar, Claude Code hooks, weather, clipboard reactions, personality) ships as a plugin in the app bundle's plugins/ directory. You can read any of them as a reference implementation.
How to read this guide
- Getting started — ship a hello-world plugin in five minutes.
- Manifest — every field, required and optional.
- Permissions & capabilities — the trust model. Read before shipping anything with
exec. - Lifecycle & events —
onLoad,onUnload, the event bus, the URL scheme. - Settings & storage — declarative settings UI, typed reads with manifest defaults.
- Quips & the coordinator — push ambient chatter and let the host decide timing.
- Debug & distribute — logs, zip, restart, done.
Where to look for specifics
The API reference is the exhaustive method-by-method surface, generated from petty.d.ts. Drop that file next to your plugin's main.js for full editor autocomplete in VS Code.