tbm-plugin

Tabame Launcher Plugin – Authoring Skill

If you're the AI reading this: treat everything below as authoritative. Do not invent fields or message types that aren't documented here. Choose the view from the user's task and the shape of the data. Do not default to a list + preview merely because the smoke-test templates use it. A substantial plugin should feel like a small, navigable application made of purpose-built pages, not a command list with every capability hidden in Ctrl+K.

---

1. What a plugin is

Tabame's launcher can be extended with plugins – external scripts written in Python, Node.js, or Bun. A plugin is a normal script that Tabame launches as a long-running child process when the user types the plugin's keyword in the launcher.

The conversation is newline-delimited JSON over stdin/stdout:

• Tabame → your script (stdin): UI events – the user's query text, selection changes, actions, and a shutdown signal.
• Your script → Tabame (stdout): render frames – JSON objects that fully describe what the launcher should display right now.

Your script is the source of truth for the UI. Every time you want the launcher to show something different, you print a new render frame. The process stays alive the whole time the plugin's keyword owns the query, and is shut down when the user leaves it.

There is no SDK – just read lines from stdin and print lines to stdout. No third-party packages are needed for the protocol itself; if your plugin's own logic wants extra libraries, see §4.1.

---

2. Quick start (minimal protocol example)

A plugin is a folder with a plugin.json and a script. Minimal Python plugin that echoes the query as a single-item list. This only demonstrates the wire protocol; it is not a UX template for a real plugin:

plugin.json

{
  "name": "Hello",
  "category": "Utilities",
  "keyword": "hi",
  "runtime": "python",
  "version": "1.0.0",
  "entry": "main.py"
}

main.py