Every plugin has a file named garage-plugin.toml in its folder. Keys are snake_case. An unknown key is an error, so a typo shows at install and not at run time.
garage checks the whole file before anything runs. Each error names the field, for example actions[1].command: missing.
id matches ^[a-z][a-z0-9-]{1,30}$, is unique, and is not a reserved word (session, workspace, focus, jump, overlay, view, hooks, app, pet, daemon, chord, plugin, pane, core).
Local ids (action, pane, widget) match ^[a-z][a-z0-9_-]{0,31}$. No dots or colons. The full id of an action is <plugin>:<id>.
api_version must be one garage supports. See versioning.
requires lists feature names from GET /api/plugins/features. If one is missing garage refuses to load the plugin and says which. Use name for a flag, or name:value for a list, for example events:session.turn or slots:tile.gutter.
Permissions must be honest: a manifest with [[widgets]] must declare ui.widgets, with [[panes]] must declare ui.panes, and with a button that runs a core action must declare ui.navigate (navigation only) or core.actions.
Actions: exactly one of command and pane.
Events: timer needs every_secs of at least 5. Other events must not have it.
Buttons and clicks: on_click is a core id, one of this plugin’s own action ids (this-plugin:action or the bare local id), never another plugin’s.
[[cli]]: the name must not be a core command (tui, daemon, restart, plugin, host, help, version), a name kept free for core (start, stop, status), or another plugin’s. Only one installed plugin may set fallback = true.
[release] needs checksums and at least one asset. Keys are <macos|linux|windows>-<aarch64|x86_64>.
Slots: rail.row, tile.title.right and tile.gutter are about one session. rail.header and rail.extra_rows are about one workspace. strip.right is global.
A command is an array: the program, then its arguments. There is no shell, so $(x) or * stay as typed. If you want a shell, write ["sh", "-c", "..."]; the install preview prints such commands in full.
A first element with no slash is looked up on PATH. One that starts with ./ or {plugin_dir} is looked up in the plugin folder.
In [[build]] commands {plugin_dir} is a staging folder that is moved afterwards. Do not record that path in build output; use paths relative to the plugin folder.
The tables below are generated from the same JSON schema that editors use. claude-garage plugin schema prints it, and it lives in schemas/garage-plugin.schema.json.