Examples

The Waydir repository includes ready-to-copy examples in docs/examples/plugins/. They are also loaded by integration tests, so they are the best source for current working patterns.

Bundled plugins

Plugin	Permissions	Shows
selection-count	none	Minimal context action using ctx.count and waydir.toast.
backup-copy	exec	Selection filter for files and a quick external cp command.
templates	fs	Toolbar, background menu, menubar actions, shortcut, settings, dialog, and file writes.
open-vscode	exec	Toolbar button and folder context action using a configurable editor command.
sevenzip	exec	Grouped context menu, archive filters, dialogs, run_task, and extraction workflows.

Open current folder in an editor

Pattern: toolbar action, user setting, and exec.

local function editor_command(ctx)
  local cmd = (ctx.settings or {}).command
  if not cmd or cmd == "" then
    return "code"
  end
  return cmd
end

waydir.register({
  id = "open_vscode",
  title = "Open in VS Code",
  menu = "toolbar",
  icon = "icon.svg",
  settings = {
    { id = "command", type = "text", label = "Editor command", default = "code" },
  },
  run = function(ctx)
    if not ctx.dir or ctx.dir == "" then
      return
    end
    waydir.exec(editor_command(ctx), { ctx.dir })
    waydir.notify({
      title = "VS Code",
      message = "Opening " .. ctx.dir,
      level = "info",
    })
  end,
})

Dialog round-trip

Pattern: first run opens a modal, second run receives ctx.form.

waydir.register({
  id = "custom_archive",
  title = "Add to archive...",
  icon = "sliders",
  when = { min = 1, in_archive = false },
  run = function(ctx)
    if not ctx.form then
      waydir.dialog({
        title = "Add to archive",
        fields = {
          { id = "name", type = "input", label = "Archive name" },
          { id = "format", type = "select", label = "Format",
            options = { "7z", "zip", "tar.gz" }, default = "7z" },
        },
        submit_action = "custom_archive",
      })
      return
    end

    waydir.run_task({
      title = "Create " .. ctx.form.name,
      cmd = "7z",
      args = { "a", ctx.form.name .. "." .. ctx.form.format, table.unpack(ctx.paths) },
      cwd = ctx.dir,
      timeout = 3600,
    })
  end,
})

Recommended patterns

• Use settings for user-editable configuration and defaults.
• Use ctx.plugin_dir when calling scripts bundled next to init.lua.
• Use group for related context actions, such as archive formats.
• Use run_task for conversion, compression, indexing, upload, and extraction.
• Keep when filters strict so actions appear only where they make sense.
• Ask for exec and fs only when the plugin really needs them.