Plugin development

01 — Shape

File and module layout

Each plugin is a directory whose name is the plugin id. The host loads exactly one file:

lua/plugins/examples/<id>/init.lua

There is no user plugin directory. To ship a plugin, add it under that tree (or point TRAASH_LUA_PATH at a tree that contains it) and list the id in config.plugins.

-- lua/plugins/examples/my-chip/init.lua
return {
  setup = function()
    traash.segments.mychip = function()
      return "ok"  -- empty string hides the chip
    end
    traash.on("on_bell", function()
      traash.notify("Bell")
    end)
    traash.log("my-chip: ready")
  end,
}

The file may instead return a function; that function is called as setup. Any other return value is ignored after load.

Enabling

plugins = {
  "git-status",
  "cwd-short",
  "my-chip",
}

Config accepts at most 16 plugin ids. Order is load order. A failed dofile or setup error is logged; that plugin is marked failed and skipped.

02 — Lifecycle

When plugins run

1. Host creates the global traash table (API, empty segments, hooks, ctx).
2. Each enabled id is loaded and setup() runs once.
3. Every ~0.5s the status bar rebuilds (calling every traash.segments.* function) and on_tick fires.
4. Other hooks fire from terminal/mux state in the main loop.

03 — API

Host functions

Do not invent host APIs. Plugins cannot draw UI, open windows, or bind keys directly — use segments, hooks, notify, clipboard override, or run_action.

Queued actions

run_action stores a single pending name. The main loop drains it once per frame, so a second call in the same frame overwrites the first. Valid names are the action ids in the keymap, including overview.

04 — Hooks

Events

Inactive tabs also get an attention badge on output, BEL, or command-finished even when those hooks do not fire (for example BEL while focused).

05 — Status

Segments and ctx

Status styles are Lua files under lua/status/<id>.lua returning function(ctx) … end. Before the style runs, the host fills ctx.seg by calling every function in traash.segments. Empty strings are omitted.

Keep segment functions cheap. Status and on_tick run about twice a second. Cache subprocess work (see git-status).

06 — Side effects

Clipboard and notifications

In on_copy, call traash.set_clipboard(text) to replace what the host puts on the clipboard (the copy-enhancements example trims trailing whitespace this way).

traash.notify is a short-lived desktop bubble, not a persistent inbox. On Linux it replaces the previous traa.sh notification. If notify-send is missing, the message is still logged. On macOS it uses Notification Center via osascript. Prefer rate-limiting in the plugin (the bell example waits 15 seconds).

07 — Constraints

Practical limits

• Trusted, unsandboxed Lua in the UI process — treat plugin code like the rest of the app.
• Bundled path only: plugins/examples/<id>/init.lua.
• At most 16 ids in config.plugins.
• Status refresh ~2 Hz; one queued run_action per frame.
• No plugin hot reload; no user plugin dir; reload_config does not re-init plugins.
• No direct drawing. Overlays, tabs, and the overview are host UI.

08 — Examples

Bundled plugins

Enabled by default in lua/defaults/config.lua:

Optional examples (not default-enabled — add them to config.plugins):

Minimal hook example

-- lua/plugins/examples/notify-on-bell/init.lua
local last = 0
return {
  setup = function()
    traash.on("on_bell", function()
      local now = os.time()
      if now - last >= 15 then
        last = now
        traash.notify("Bell in traa.sh")
      end
    end)
  end,
}