Plugin system

Waydir plugins add small workflow actions to the file manager. A plugin can show items in the selection context menu, background context menu, top Plugins menu, location toolbar, and keybindings. It can also register global and per-pane status bars for continuously visible information.

Plugins are written in Lua. There is no build step: drop a folder into the plugins directory, reload plugins from Preferences -> Plugins, and the actions become available.

Mental model

A plugin is one folder:

my-plugin/
  manifest.json
  init.lua

On reload, Waydir scans the plugins directory, reads every manifest.json, rejects unsupported API versions, and runs init.lua once in a sandbox to collect waydir.register(...) contributions.

When a user invokes an action, Waydir starts a fresh Lua VM, runs the same init.lua, finds the matching action id, calls run(ctx), and applies the effects emitted through the waydir.* API.

Runtime guarantees

Area	Behavior
API version	This build supports api_version: 2.
Sandbox	Lua gets table, string, math, and waydir; no os, io, or require.
Timeout	Lua load and invoke are capped at 5 seconds.
State	Lua globals do not persist between clicks. Use settings for durable state.
Permissions	External commands need exec; file reads/writes and queued file operations need fs.

Where actions can appear

Surface	Use it for
Selection context menu	Actions that operate on selected files or folders.
Background context menu	Actions that operate on the current directory.
Top Plugins menu	Global plugin commands and configuration helpers.
Toolbar	Frequent current-folder actions.
Shortcut	Fast keyboard-driven workflows.
Status bar	Continuously visible info, global or per pane.

What to read next

• Quick start creates the smallest useful plugin.
• Manifest covers metadata, API version, and permissions.
• Actions explains waydir.register, ctx, and when.
• UI surfaces covers menus, toolbar buttons, settings, dialogs, icons, and shortcuts.
• Status bars covers global and per-pane status bars.
• Host API lists every waydir.* function.
• Examples points to bundled working plugins.