Plugins

One package can carry skills, commands, sub-agents, MCP servers and hooks; the install ledger belongs to the engine.

A plugin is a packaged bundle of capabilities: one plugin can carry skills, slash commands, sub-agents, MCP servers and hooks at the same time.

  • Marketplace tab: browse and install from the plugin marketplace. The "what you get after installing" on each row is computed by the engine with the very same parser it uses when loading, so the marketplace page cannot disagree with what actually shows up once installed.
  • Update checks: opening the plugin page, returning focus to a window and background checks fetch the latest catalog. Results are reused for five minutes, and a background check runs every thirty minutes. Checks never install a release automatically, and the last catalog remains available offline. The refresh button checks again immediately.
  • Updates: marketplace cards and the installed list show the installed version, the available version and an "Update to" button. The updates view lists available releases, and "Update all" processes them in a queue. Each plugin has its own progress and result, so updating one plugin leaves other plugins available to browse and manage. Failures preserve the current installation and show a reason with a retry action. Updates preserve the enabled state and plugin data, and the engine rejects stale update requests.
  • Installed tab: the enable/disable switch. Note that plugin on/off is application-wide, with no project scope — once enabled it is visible in every session.
  • "Loaded / failed to load" in the installed list is the runtime state of one particular session, not a global property: the same plugin can be healthy in a new session while an older session still holds its previous state.

How installing and activation work:

  • The ledger belongs to the engine and lives in the [plugins] section of its own config file ~/.klaus/config.toml, one record per plugin with its name, source, install path, install time and enabled flag. The engine reads and writes this file, so do not introduce a second writer that changes its shape — the engine parses it at startup, and a wrong shape means it will not boot. Registered marketplace catalogs are recorded in the [marketplaces] section of the same config.
  • Installing has two stages: the client first fetches the package into a staging directory (a local copy, or a git fetch — repository URLs, the owner/repo shorthand and fetching just one subdirectory of a repository are all supported), then hands it to the engine to validate, copy into its own storage area and write the ledger. The staging directory is cleaned up whether it succeeded or failed, so a failed install never leaves half a plugin behind.
  • Toggling flips the enabled flag in the ledger. After installing, updating, enabling or disabling, the page describes activation using the engine's receipt: idle sessions can receive published plugin changes, while a running turn uses the new version on its next turn. A restart is offered only when the engine explicitly requires a new connection or restart. If the plugin was saved but a subsequent projection refresh fails, the saved result remains successful and the refresh problem is reported separately.
  • Uninstalling removes both the ledger row and the copy in the storage area. The built-in ones (the browser, for example) are tagged as built-in sources: they can be disabled but not uninstalled.
  • The skills, commands, sub-agents, MCP servers and hooks inside a plugin are loaded by the engine from the ledger and tagged with their source; the client does not report them again (otherwise a plugin's hooks would fire twice per event).