wox-plugin-creator

Wox Plugin Creator

Quick Start

• Scaffold a Node.js plugin (clones template repo):
  • python3 scripts/scaffold_wox_plugin.py --type nodejs --output-dir ./MyPlugin --name "My Plugin" --trigger-keywords my
• Scaffold a Python plugin (clones template repo):
  • python3 scripts/scaffold_wox_plugin.py --type python --output-dir ./MyPlugin --name "My Plugin" --trigger-keywords my
• Scaffold a single-file SDK plugin (uses local templates; plugin-id auto-generated; writes one file into the live user plugin directory so a running Wox instance can load it immediately). Omit --output-dir; default is ~/.wox/wox-user/plugins/single-file/ (Windows: %USERPROFILE%\.wox\wox-user\plugins\single-file\):
  • Auto-detect this machine: python3 scripts/scaffold_wox_plugin.py --type singlefile --name "Weather" --trigger-keywords weather
  • Explicit Node.js: python3 scripts/scaffold_wox_plugin.py --type singlefile-nodejs --name "Weather" --trigger-keywords weather
  • Explicit Python: python3 scripts/scaffold_wox_plugin.py --type singlefile-python --name "Weather" --trigger-keywords weather

Choose a plugin type

• Single-file SDK plugin: one .py or CommonJS .js file with full Public API, loaded into the existing Python/Node runtime host. No extra process per query. Create and edit only ~/.wox/wox-user/plugins/single-file/Wox.Plugin.<Name>.js (or .py); Wox watches that directory and reloads on save. Requires Wox 2.4.2+; header MinWoxVersion must be "2.4.2".
• SDK plugin (.wox): multi-file package with dependencies, resources, TypeScript, and plugin.json.

Node.js first version must stay CommonJS (module.exports.plugin) and must not import @wox-launcher/wox-plugin.

Choose a runtime language

Honor an explicit Python or Node.js request from the user, including a .py or .js output filename.

When the user does not specify a language, detect this machine before scaffolding. Do not default to Python.

1. Run python3 scripts/detect_local_runtime.py (use python if python3 is missing). It prints nodejs, python, or none.
2. If that script cannot run, check the floors yourself: node --version for Node.js 20+, and python3 --version for Python 3.10+. On Windows also try py -3 --version and python --version.
3. Decision:
   • Only one runtime meets the floor → use that runtime
   • Both meet the floor → use Node.js
   • Neither meets the floor → ask the user which language they want
4. Map the choice to --type: singlefile-nodejs / singlefile-python, or nodejs / python. --type singlefile applies the same detection inside the scaffold.

Workflow

1) Scaffold plugin files

• Use scripts/scaffold_wox_plugin.py for nodejs, python, singlefile, singlefile-python, or singlefile-nodejs.
• Pass --name and --trigger-keywords for every runtime. The scaffold exits without them. --output-dir is required for packaged SDK plugins; omit it for single-file SDK plugins so the file lands in ~/.wox/wox-user/plugins/single-file/.
• For Node.js and Python packages, the scaffold clones the official template repos and replaces placeholders like {{.ID}}, {{.Name}}, {{.Description}}, {{.TriggerKeywordsJSON}}, {{.Author}}.
• Before starting work in a new SDK plugin project, run make init in the project root when the project has not been initialized yet.
• Single-file SDK plugins are single-file host-loaded plugins. Prefer filenames like Wox.Plugin.<Name>.js or Wox.Plugin.<Name>.py.
• Single-file SDK destination: create and implement the plugin as one file in ~/.wox/wox-user/plugins/single-file/ (Windows: %USERPROFILE%\.wox\wox-user\plugins\single-file\). That directory is what a running Wox instance loads; saving reloads after about 500ms, so the user can query the trigger keyword immediately. Omit --output-dir when using the scaffold, or write the file there directly from assets/single_file_plugin_templates/. Do not also create a copy under the current repository (plugins/, workspace root, or a new folder). Pass --output-dir only when the user asks for a different path.
• Do not put companion files (*.test.js, README, extra modules) in the live directory. Wox loads every .js and .py there as a plugin.
• Single-file SDK plugins must set header MinWoxVersion to "2.4.2". The scaffold applies this default when --min-wox-version is omitted. Do not lower it; Wox 2.4.2 is the first release that can load this plugin type, and store/CI reject older floors.
• For single-file SDK plugins, the scaffold copies templates from ~/.wox/ai/skills/wox-plugin-creator/assets/single_file_plugin_templates/ (or the repo .agents/skills/wox-plugin-creator/assets/single_file_plugin_templates/ fallback).
• Prefer standard library features; avoid third-party dependencies unless absolutely necessary. Single-file SDK plugins cannot use pip/npm packages.
• For SDK usage and API details, read references/sdk_nodejs.md or references/sdk_python.md.
• For plugins declaring querySelection, return results only for selection types and content the plugin can process. Return an empty results list for unsupported, missing, or empty selection data instead of showing usage or help rows for unrelated selections.
• Keep a result on the row. Title is the name to scan. SubTitle is one short identity line, such as a code, place, or source. Tails are the few facts that must stay visible, such as a price and its change. Use at most three tail tags on one result. A fourth tag can be clipped, so part of a tag is not shown. Put any further fact in the subtitle, the copied text, or a preview. Do not add Preview for a quote, status, short record, or anything that fits on that row.
• A text tail is already a capsule. Use an SVG image tail only when that capsule must also contain an icon. Match the launcher metrics below, and see Simulated tail tags.
• Refresh a visible row in place with UpdateResult / update_result. Remember the results returned by the latest query(). Replace that list on the next query. When a background refresh or an action changes a row that is still on screen, call UpdateResult with the same result Id and only the fields that changed (Title, SubTitle, Icon, Tails, Actions). The query text stays put and the list does not reload. Use RefreshQuery / refresh_query only when rows must be added or removed and UpdateResult cannot express that. Do not use ChangeQuery to redraw results.
• Add Preview only for a large body that cannot fit the row: a long document, many fields, a chart, a gallery, or syntax highlighting. When a preview is required, use markdown for prose, lists, links, and images. Use text or image when that is the whole preview. Use webview HTML only after markdown cannot express it, such as syntax highlighting, folding, or an interactive layout. HTML is the last option because the webview can steal query focus, miss launcher theme colors, and hit layout bugs. There is no separate html preview type; HTML uses webview with a JSON-encoded html field and no local HTTP server. See the HTML preview examples in the SDK references.
• Do not rasterize documents as SVG/image previews; those scale as pictures, cannot select text, and do not follow theme colors.
• When HTML is required, follow the current Wox theme. Call GetThemeColors / get_theme_colors (Wox >= 2.4.5) when building the HTML and paint opaque Background, Text, SecondaryText, Border, Accent, AccentText, and Selection. Use Dark to choose a light or dark syntax palette. Do not hardcode only a dark page, and do not rely on transparent or prefers-color-scheme as a substitute for the launcher palette. Include a theme color in cacheKey so the preview refreshes after a theme change. If the API is missing, fall back to a dark and a light default.
• For inline command arguments or atomic query blocks, read QueryHint. Command declarations contain suffix templates; ChangeQuery contains a complete instance. Keep legacy text parsing when structure is absent.
• For query-scoped filters or sort controls, return QueryResponse.Refinements and read references/refinements.md before assigning hotkeys.
• For plugin.json, SettingDefinitions, QueryRequirements, validators, dynamic settings, and feature flags, read references/plugin_json_schema.md first.
• When implementing an SDK or single-file SDK plugin, also register Plugin Tools in init() for capabilities other plugins should be able to call. Query results and actions stay for the user; tools expose the same work as structured operations. Read references/plugin_tools.md first. Requires Wox >= 2.4.5 (MinWoxVersion "2.4.5" or newer). Do not declare tools in plugin.json.
• SDK and single-file SDK plugins should support MRU unless the plugin is clearly unsuitable. Declare the mru feature, put restore identity on action ContextData, and register OnMRURestore / on_mru_restore in init(). The restore callback must return immediately from memory or local cache. Wox waits 300ms for each start-page MRU restore, then discards that item, logs the timeout, and shows the next MRU item. Do not fetch, scan disk, or call host APIs inside the callback. Skip MRU only for context-dependent, one-shot, diagnostic, or inbox-style plugins, and say why in the implementation notes.
• Persist user settings through the Public API (GetSetting / SaveSetting / SetSetting / OnSettingChanged, or Python get_setting / save_setting / set_setting / on_setting_changed). A normal setting write is cloud-synced and follows the user across machines. Use these APIs for preferences, API keys, favorites, and account configuration.

Cache stays out of the settings API

Anything the plugin can rebuild is cache: fetched JSON, subject or entity snapshots, search indexes, downloaded files, and thumbnails. Write t

Content truncated.