All guides

Install a plugin ZIP

Install an AI-created plugin manually and check its behavior in smabar.

Read as Markdown
On this page

Build with ChatGPT or Claude explains how an AI creates the archive. Local plugin code runs with your user permissions. Read the files before installation.

Expected ZIP structure

my-plugin/
  smabar.json
  plugin.py
  views.py             (if imported)
  locales/
    en.json
    de.json
  README.md
  LICENSE              (when required by reused source)
  ...other imported modules and required assets

The manifest’s id must be my-plugin in this example. The entry script named by the manifest must exist. Choose a new ID for a new plugin; simply renaming a bundled example’s folder does not change its manifest or tile IDs.

Install

  1. Extract the ZIP into a temporary folder outside .smabar. Inspect the complete plugin folder and its README. Check for missing files, secrets, unexpected executables or links outside the folder.
  2. Quit smabar so it cannot observe a partially copied plugin. Open the plugins directory: on Linux/macOS, ~/.smabar/plugins/; on Windows, %USERPROFILE%\.smabar\plugins\ in File Explorer. Create the plugins directory if it does not exist.
  3. Check that no folder with the same ID exists. If it does, stop and ask for a new plugin ID or make an explicit update with a backup. Do not merge extracted files into an existing plugin.
  4. Move the whole my-plugin folder into the plugins directory. The result must be plugins/my-plugin/smabar.json, not an extra nested my-plugin/my-plugin folder.
  5. Start smabar and check the plugin in its settings. Allow any documented Python dependency preparation to finish. smabar provides the runtime and SDK; follow the plugin README for additional local configuration.

Verify in the app

  • Check the tile and every provided flyout, hover or popup: no clipped text, raw translation keys, missing icons or inaccessible controls.
  • Try actions and settings; check loading, empty and failure states. If the plugin uses a provider or external service, check it on your own operating system.
  • Restart smabar and confirm that intended settings and stored data remain available.
  • Review ~/.smabar/logs/plugin-my-plugin.log (Windows: %USERPROFILE%\.smabar\logs\plugin-my-plugin.log) for errors and markup warnings. The debugging reference explains them. Remove secrets and personal data before sharing excerpts.

The archive’s syntax and file checks do not prove its appearance or behavior in the running app. Give your AI the actual error or a screenshot for a correction. Keep backups outside .smabar/plugins/; a backup inside that directory may itself be discovered as a plugin.