Plugins

A plugin adds gated actions on a local app, such as Mail or Things 3. Each action is a tool, so an agent runs it behind the same Touch ID prompt and audit log as a secret read.

passbox plugin add mail                         # first-party, bundled in the binary
passbox plugin list                             # installed plugins and their tools
passbox plugin mail recent --count 5            # run a tool, approved and audited
passbox plugin remove mail

The same tools appear over MCP as mail.recent, mail.send and so on, so an agent calls them through the server. Every call prompts. The broker approves and audits, the caller runs the command, so it keeps your GUI session. A value is passed as a whole argument to the command, never spliced into a script, so it cannot become code.

First-party plugins:

mail drives Mail through osascript, which ships with macOS. The first read raises the macOS automation prompt for Mail once.

calendar and things3 shell out to a CLI, so each has to be installed:

brew install ical-buddy                          # calendar
brew install ossianhempel/tap/things3-cli        # things3

calendar uses icalBuddy rather than raw AppleScript, because AppleScript reports a recurring event's series start instead of the occurrence date.

git and gh run in the directory you call them from, not the plugin directory, so they act on the current repository. Both prompt on every call, so an agent cannot push or open a PR without your fingerprint.

A tool whose command is missing is refused before it prompts, with the install line above.

Write your own plugin as a directory with a plugin.toml, then passbox plugin add <dir>. A tool declares its params and a run command where {param} is one whole argument.

Each plugin carries a version. passbox plugin update <name|dir> refreshes an installed plugin, and plugin list flags a first-party plugin whose bundled version is newer than the installed copy, which is what happens after a brew upgrade.