Repository navigation
Plugin Usage EN
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.
- Local plugins with
worker.js/mainhave 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:readalso warn that access includes metadata of private starred repositories. Anetwork:permission gets its own notice: the plugin page will reach allowlisted hosts through the Host proxy using your GitHub Token (currently read-only endpoints ofapi.github.comonly). - The Host never gives plugins your GitHub token, AI keys, or WebDAV passwords.
- Open the desktop app.
- Go to Settings → Plugins.
- 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.
- In Settings → Plugins, click Install local plugin.
- Choose the plugin directory (it must contain
manifest.json). - 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.
- Flip the switch on the plugin card.
- Read the confirmation: Workers are not a sandbox, plus the requested permissions.
- 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.
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. Actions with opensPage instead open the plugin page in a modal, handed the current repository's metadata and README (no Worker runs) |
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; modal actions open the same pages with a repository context on top |
repositoryProcessors exist as a Host API, but there is no dedicated UI button for them.
Plugins cannot drive Host UI directly. They return an intent that the Host applies:
- Copy to the clipboard (
clipboard:writerequired) - Save as a text file
- Open an HTTPS URL in the system browser (
external:openrequired; credentials are rejected) - Show a notice
- Open a Release.
- Click Analyze under “Plugin asset recommendations”.
- Review the file name, reason, and confidence.
- If the plugin has
downloads:create, click Host download. - 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.
Page plugins may request web:search. It is off by default; there is no bundled public instance.
- At the top of Settings → Plugins, enter a SearXNG HTTPS URL you trust, such as
https://search.example.com. - The instance must enable JSON output.
- 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.
Page plugins may declare network:api.github.com and issue read-only GET requests to GitHub through the Host proxy. Only api.github.com is supported today, and endpoints are allowlisted: repository details, commit / participation / code-frequency stats, contributors, languages, releases, pull requests, tags, stargazers, the community health profile, security advisories, and user profiles.
- Requests authenticate with your own GitHub Token; without a configured Token the request is anonymous (GitHub caps anonymous calls at 60 per hour).
- The capability is granted once during the enable confirmation — no per-request prompts; the confirmation shows a dedicated notice.
- The Token itself never reaches the plugin page; the page only receives the response and an anonymized account tag.
- The Host rejects all redirects; responses time out after 15 seconds and cap at 4 MiB.
- GitHub returns 202 the first time a stats endpoint is requested (statistics are being generated); plugins should ask you to retry later.
The bottom of Settings → Plugins has a “Community plugin registry” section that compares your installed plugins against the officially maintained static registry. It is informational only: nothing is downloaded, installed, updated, or disabled automatically.
- Available updates list the newest version; if that version requires new permissions they are shown too, so you know re-confirmation will be needed
- Up-to-date, not-listed, and version-uncomparable plugins are labelled as such
- Revoked or blocked plugins show the reason and offer a Disable now button
- Refresh re-fetches the registry; if one list fails to load, the valid part is still shown with an error notice
Registry data comes from the registry/ directory of the main repo: community-plugins.json records each reviewed, pinned plugin version (SHA-256, permissions, network declarations), and removed-plugins.json records revocations and blocks. The registry starts empty in this first stage and only accepts page plugins (no native-code manifest.main); to get your plugin listed, follow the contribution process in that directory's README.
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.
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-info-card |
Use your configured AI to turn repository metadata and the README into a shareable info card; copy or save a PNG | Repository card menu Plugin actions → Generate repository info card (modal); also openable from Settings |
repo-insights |
Pulls GitHub metrics live through the Host's read-only proxy into a dashboard: health score, commit activity, code churn, languages, contributors, release cadence, community health, security advisories, and star trends, with optional AI recency analysis | Repository card menu Plugin actions → Repo insights (modal); also openable from Settings |
Read worker.js or ui/ in that directory before enabling.
| 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. repositories.search looks at the in-memory sanitized snapshot, not live GitHub (page plugins with a network: permission can reach GitHub's read-only endpoints live through the Host proxy) |
| 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 |
| Plugin page network request fails | Without a configured GitHub Token the request is anonymous (60 calls per hour) — add your Token in Settings; GitHub returns 202 the first time a stats endpoint is hit (statistics generating), retry later; redirects and oversized responses are rejected by the Host |
| Community registry fails to load | The registry lives on raw.githubusercontent.com; check your network. A partial failure keeps the valid list and reports the rejected count |
| Unexpected local behaviour after enabling a Worker plugin | Disable and uninstall immediately. Workers are not a sandbox |
Refresh rescan the plugins/ directory.