Skip to content

Plugin developer reference

A plugin adds something to garage. It can add a key, a button, a widget, a pane, an event hook or a command line subcommand.

A plugin is a folder with a file named garage-plugin.toml and any program you like. It can be a shell script, a Rust binary, a Node script. garage runs the program and gives it information. The program can call garage back over a small HTTP API on your machine.

This is plugin API version 1. It is frozen: see versioning.

You want to Use Page
Run a command on a key, a click or from the palette [[actions]] actions
React when something happens [[events]] events
Show text or an animation in the wall [[widgets]] widgets
Add a clickable label [[buttons]] widgets
Show a full program in a tile, overlay or popup [[panes]] panes
Add claude-garage <word> [[cli]] cli
Keep files between runs state folder storage
  1. Quick start: a plugin in 10 minutes.
  2. Manifest reference: every key of garage-plugin.toml.
  3. Permissions: what to ask for, and the two dangerous ones.
  4. Events: names and payloads.
  5. Slots and widgets: where things show and the JSON format.
  6. Actions: and the confirm rule.
  7. Panes
  8. CLI commands: and the fallback.
  9. Storage
  10. HTTP API and environment: routes, variables, run context.
  11. Security model: no sandbox. Read this before you install a plugin.
  12. Versioning

You do not need an SDK. Any language that can read an environment variable and make an HTTP request works.

The plugins in plugins/ ship with garage and use only this public API: hello (smallest), usage-bar (timer and widget), pit-pet (animation), turn-markers (gutter), closed-chats (extra rows), quick-send (pane and session input), tile-buttons (buttons only, no program), alerts (event hook that plays sounds and shows banners itself, with a CLI command).

Terminal window
claude-garage plugin link ./my-plugin # develop: use a local folder
claude-garage plugin install owner/repo # install from GitHub (shows a preview first)
claude-garage plugin list
claude-garage plugin logs my-plugin -f # follow the log
claude-garage plugin disable my-plugin
claude-garage plugin schema # JSON schema of garage-plugin.toml