Guide · Getting started

Your first plugin

A plugin is a folder with two files. Here's the shortest path from zero to shipping.

1. Make the folder

Plugins live at ~/Library/Application Support/Petty/Plugins/. Create a folder; its name must match the plugin's id.

mkdir -p ~/Library/Application\ Support/Petty/Plugins/hello-world
cd ~/Library/Application\ Support/Petty/Plugins/hello-world

2. Add a manifest

manifest.json declares what your plugin is and what it's allowed to do.

{
  "id": "hello-world",
  "name": "Hello World",
  "author": "You",
  "version": "1.0.0",
  "description": "Says hello when Petty starts.",
  "script": "main.js",
  "capabilities": ["watchers"],
  "permissions": []
}

3. Add a script

main.js is where the behavior lives. The petty.* global is injected for you.

function onLoad() {
  petty.pet.showBubble("Hello from my first plugin!", 4);
}

4. Restart Petty

Quit and relaunch. Your plugin loads automatically — no install step, no sign-in, no marketplace.

Directory layout

Any supporting files live next to the manifest.

Plugins/
└── my-plugin/              ← Folder name MUST match manifest.id
    ├── manifest.json       ← Required
    ├── main.js             ← Referenced by manifest.script
    └── assets/             ← Optional — any supporting files

Petty validates plugins on load. If validation fails (invalid manifest, script path traversal outside the plugin folder, unknown permissions, …), the plugin is silently skipped. Check Console.app for [Plugin <id>] error logs.

What to learn next

  1. Manifest — fields for author, homepage, icon, settings, rate limits.
  2. Permissions — before adding network or exec.
  3. API reference — the full petty.* surface.