Plugin Usage EN

Plugin usage

For desktop users. To build a plugin, see Plugin development. 中文：插件使用.

The plugin system is available only in the Electron desktop app. The browser UI and Docker frontend image have no install path.

Safety

• Local plugins with worker.js / main have full Node.js access. The Worker isolates crashes and timeouts; it does not stop malicious code from reading local files, environment variables, or opening its own network connections.
• Install and enable only code you have reviewed and trust.
• Page plugins run in a restricted iframe. They cannot read the Host DOM, tokens, or Electron APIs.
• Enabling lists every permission from the Manifest. repositories:read / privateRepositories:read also warn that access includes metadata of private starred repositories.
• The Host never gives plugins your GitHub token, AI keys, or WebDAV passwords.

Open plugin settings

1. Open the desktop app.
2. Go to Settings → Plugins.
3. If you see “The plugin system is currently available only in the Electron desktop app”, you are not on the desktop client.

Installed plugins live under the app user-data directory:

OS	Directory
macOS	~/Library/Application Support/GitHub Stars Manager/plugins/
Windows	%APPDATA%\GitHub Stars Manager\plugins\
Linux	~/.config/GitHub Stars Manager/plugins/

plugin-data/ (isolated storage) and plugin-logs/ (sanitized logs) sit next to that folder. Do not edit those files unless you are debugging.

Install

1. In Settings → Plugins, click Install local plugin.
2. Choose the plugin directory (it must contain manifest.json).
3. After a successful install the plugin appears in the list, Disabled.

The Host copies the directory and rejects:

• Symbolic links
• More than 2000 files, or more than 50 MiB total
• Invalid / oversized manifest.json (256 KiB max)
• Entry files that resolve outside the plugin directory
• A plugin ID that is already installed

Official examples are in examples/plugins/. After cloning the repo, install by selecting that subdirectory.

Enable

1. Flip the switch on the plugin card.
2. Read the confirmation: Workers are not a sandbox, plus the requested permissions.
3. Click Confirm and enable.

The status becomes Active. If Manifest permissions changed since the last grant, the next launch moves the plugin to Error and asks you to confirm again.

Disable stops the Worker and closes any open plugin page. Enabling again still requires every current Manifest permission.

Where plugins appear

Only contributions from plugins that are enabled and Active are shown.

Contribution	Where	What it does
repository-card actions	Stars view, repository card menu	Runs on the current repository, e.g. copy Markdown
bulk-toolbar actions	Plugin menu on the bulk toolbar after multi-select	Runs on the selected repositories
exporters	The same bulk-toolbar plugin menu	Builds a text file and triggers a download
Release processors	“Plugin asset recommendations” on a Release	Analyze recommends an asset; Host download appears only with downloads:create
pages	Open page: … on the plugin card in Settings → Plugins	Opens inside a sandboxed iframe on the settings page

repositoryProcessors exist as a Host API, but there is no dedicated UI button for them.

Repository action results

Plugins cannot drive Host UI directly. They return an intent that the Host applies:

• Copy to the clipboard (clipboard:write required)
• Save as a text file
• Open an HTTPS URL in the system browser (external:open required; credentials are rejected)
• Show a notice

Release recommendations and downloads

1. Open a Release.
2. Click Analyze under “Plugin asset recommendations”.
3. Review the file name, reason, and confidence.
4. If the plugin has downloads:create, click Host download.
5. Confirm the source, file name, and save location in the native dialog.

The plugin never receives the download URL or local path, and it cannot install the file. Cancelling the save dialog is not an error.

Plugin web search (SearXNG)

Page plugins may request web:search. It is off by default; there is no bundled public instance.

1. At the top of Settings → Plugins, enter a SearXNG HTTPS URL you trust, such as https://search.example.com.
2. The instance must enable JSON output.
3. Click Save search service. Saving an empty value disables search.

Each plugin query shows a confirmation with the instance URL and the full search string. Declining sends nothing. Do not put private repositories, personal notes, or secrets in the query.

The URL must be a public HTTPS hostname: no credentials, no localhost / private networks / raw IPs. The Host requests {endpoint}/search?q=…&format=json and does not follow redirects.

Uninstall

Click the delete icon on the plugin card, then choose:

Option	Effect
Uninstall, keep data	Deletes the install directory; keeps plugin-data and logs
Uninstall and delete data	Also deletes that plugin’s isolated storage and logs

The install directory is always removed. If you kept data, a later install of the same ID may still see the old storage file.

Official examples

From examples/plugins/ in the source repo:

Directory	Purpose	After enable, appears in
markdown-exporter	Copy / export stars as Markdown	Repository card menu and bulk toolbar
smart-release-recommender	Recommend a Release asset for this OS/arch	“Plugin asset recommendations” on a Release
repo-health-page	Search the local repository snapshot in an isolated page	Open page: Repository Health in Settings

Read worker.js or ui/ in that directory before enabling.

Troubleshooting

Symptom	What to do
Settings says desktop-only	Use the desktop client
Install fails	Confirm a valid manifest.json, no symlinks, size limits, and that the plugin ID is not already installed
“Invalid plugins” at the bottom of the list	Manifest or entry validation failed; the row shows the code and reason
Status Error	The card shows lastError. Common causes: Worker startup failure, call timeout (default 5s), permissions changed since last grant
Page search returns nothing	Sync stars first. Pages search the in-memory sanitized snapshot, not live GitHub
Web search fails	Check that SearXNG is HTTPS, JSON-enabled, and publicly resolvable
AI call fails	Configure and activate an AI provider in Settings; every call requires confirmation
Unexpected local behaviour after enabling a Worker plugin	Disable and uninstall immediately. Workers are not a sandbox

Refresh rescan the plugins/ directory.