Tbm Plugin

Tabame Launcher Plugin Authoring

Tabame's launcher is extensible with plugins: standalone scripts (Python, Node.js, or Bun) that Tabame runs as a long-lived child process when the user types the plugin's keyword. Communication is newline-delimited JSON over stdin/stdout – no SDK, no dependencies.

• Tabame → script (stdin): UI events (init, query, select, action, close).
• Script → Tabame (stdout): render frames – JSON objects that fully describe what the launcher shows right now.

The script is the source of truth for the UI: every time you want the launcher to display something different, you print a new render frame.

Authoritative references (read these)

The complete, authoritative protocol spec lives in the repo. Read it before writing non-trivial plugins – do not invent fields or message types not documented there:

• Full spec: skills/TABAME_PLUGIN_SKILL.md – every message type, render-frame field, item field, view type, icon name, and pattern.
• Working examples to copy from:
  • plugins/echo/ – Python demo exercising list/grid/detail/preview + actions.
  • plugins/linear/ – Node.js plugin with an HTTP API and config.json secrets.
  • plugins/caniuse/ – Node.js plugin with fetched data and detail views.

When a detail isn't covered below, consult the full spec rather than guessing.

Workflow for building a plugin

1. Clarify the shape (only if unspecified): keyword, runtime, data source, what each item shows, what Enter does, what Ctrl+K actions to offer, and which view (list / grid / detail / preview pane).
2. Pick a runtime the user has on PATH: python, node (18+), or bun. Tabame bundles none.
3. Scaffold the folder with plugin.json + entry script. Start from the matching template in §15 of the full spec, or copy the closest plugins/ plugin.
4. Implement the event loop (see contract below).
5. Install & test: drop the folder in %localappdata%\Tabame\plugins\<id>\, reopen the launcher (it rescans on every open – no restart), and type the keyword.

plugin.json (manifest)

{
  "keyword": "weather", // required – what the user types; short & unique
  "category": "Weather", // required – one canonical discovery category
  "runtime": "python", // required – "python" | "node" | "bun" (on PATH)
  "entry": "main.py", // required – script filename in the plugin folder
  "id": "weather", // optional – defaults to folder name
  "name": "Weather", // optional – shown in the discovery hint
  "description": "", // optional
  "icon": "cloud", // optional – icon name (see spec §11)
  "args": [], // optional – CLI args inserted BEFORE entry
  "enabled": true // optional – defaults to true; set false (or toggle
  //   from the Launcher Plugins manager) to hide the
  //   plugin without deleting it
}

category is mandatory in every manifest. Choose exactly one current registry value: AI Tools, Communication, Developer Tools, Entertainment, Finance, Fun & Casual, Language & Writing, Media & Design, Network Tools, Productivity, Shopping, System Tools, Utilities, Weather, or Web & Browser. Match the plugin's primary user-facing purpose and preserve the exact spelling/capitalization; do not invent variants or multiple values.

Launch is effectively <runtime> <args...> <entry>, started without a shell, with the working directory set to the plugin folder (so config.json/assets resolve relatively). Activation: the query equals the keyword or starts with keyword + " "; the keyword prefix is stripped before your script sees the text.

The protocol contract (essentials)

One JSON object per line, both directions. Flush stdout after every frame.

Messages you receive on stdin:

Minimal render frame you print to stdout:

{
  "type": "render",
  "rev": 1,
  "view": "list",
  "items": [
    { "id": "1", "title": "Hello", "subtitle": "world", "icon": "star" }
  ]
}

Full frame/item fields (views list/grid/detail, loading, emptyText, grid, detail.markdown, preview, item accessories/actions/preview) are documented in spec §6–§8.