Skip to main content

Plugins

A plugin is one JSON file: a palette label and a shell command, run through the jobs layer like any other project tool. Small on purpose — a plugin you can read in five seconds is a plugin you can trust. This page covers managing them, where they live, and the marketplace. Deploy plugins, which bind a command to a UI surface, get their own page.

Two layers​

Plugins now live in two places, and they layer the way the rest of kiln does:

  • Project — .kiln/plugins/ inside the repo. Committed, shared with anyone who clones it, and so gated on workspace trust: a freshly cloned repo runs nothing until you trust the workspace.
  • Yours — ~/.kiln/plugins/, in your home directory. Your own helpers that follow you into every project you open. They're yours, on your machine, so they need no per-workspace trust decision.

When both layers carry a plugin with the same name, the project's wins — the same project-beats-user precedence the .kiln config layers use. A project plugin shadows your user-global one, so a repo can override a helper without you losing it everywhere else.

Managing them​

Settings ▸ Plugins is the one place to see and shape both layers. Each plugin shows its command verbatim — the "read it in five seconds" promise is better kept by showing the line than by hiding it behind a form. From there you can:

  • Add a plugin to either layer with a name and one zsh line. The destructive-command guard that keeps squad-grown plugins honest warns here too, but it doesn't block you — a command you hand-author in your own trusted space is a line you'd have typed into a shell anyway.
  • Remove a plugin the manage UI added. Removal only deletes the single-plugin file it would have written, and only when that file holds exactly that one plugin — a hand-authored file carrying several plugins together is never silently gutted. When it can't cleanly remove one, it opens the file for you to edit by hand.

If the open project hasn't been trusted yet, the project section says so and offers a Trust button rather than listing commands that won't run.

The marketplace​

The marketplace is a curated shelf of official plugins — read-only one-liners over a project's own tooling: count the TODOs, list the largest files, show outdated dependencies, commits per author, and so on.

It is deliberately not an install-and-run store. Picking an entry copies its JSON into your project or your user-global plugins and shows you the command — it never executes anything, and a project plugin still waits behind workspace trust. That matters: the whole reason kiln makes you trust a workspace is so opening a repo can't run a stranger's shell line. A store that ran things on tap would be a back door around exactly that. Copy-and-review keeps the trust model intact, and every official entry is vetted to be read-only or build-only — none push, delete, or sudo.

Each entry offers two verbs: Add to project (drops it in .kiln/plugins/, for the team) and Add to my plugins (drops it in ~/.kiln/plugins/, for you everywhere). Once an entry is in a layer, that verb reads "Added".

Where the logic lives​

Plugins (Config/Plugins.swift) is the pure core — loading and stamping each layer's scope, the project-wins merge (merged(user:project:)), and the safe single-file removal. PluginMarket (Config/PluginMarket.swift) is the static, tested catalog. PluginsSettings (Config/PluginsSettings.swift) is the tab. AppState.effectivePlugins folds the two layers into the one list the palette, jobs, and deploy buttons all read.