All pages

Docs · AI features

Plugins

Availability: macOS. The engine is JavaScriptCore, which is not on Linux — see Platforms.

Plugins are JavaScript files dropped into your TRMNLY plugins folder. Each plugin runs in an isolated JS context and can contribute:

  • Tools the agent can call
  • Status-line widgets that render text into the strip above the right sidebar
  • Sidebar views that show under the Plugins tab
  • System-prompt fragments that get folded into the agent's system prompt
  • Personas (alternate prompt + tool allowlist combinations)

This is the same surface MCP servers use under the hood, so anything you can script you can ship.

Where plugins live

~/Library/Application Support/TRMNLY/plugins/

Open it from the Plugins tab → "Open plugins folder", or via the Plugins → Install… picker which copies a .js file in for you. Press Reload all (or a plugin's own Reload button) to pick up changes without restarting the app.

Minimal plugin

trmnly.manifest({
  name: 'echo',
  description: 'Echoes the input back.',
});

trmnly.tools.register({
  name: 'echo',
  description: 'Return the input string verbatim.',
  inputSchema: {
    type: 'object',
    properties: { text: { type: 'string' } },
    required: ['text']
  },
  execute: (args) => args.text,
  dangerous: false,
});

That's it. Reload from the Plugins tab and the agent sees an echo tool.

API surface

trmnly.manifest({ name, description, tools, ...permissions })
trmnly.tools.register({ name, description, inputSchema, execute, dangerous })
trmnly.statusLine.add({ id, render, intervalMs })
trmnly.sidebar.add({ id, title, render })
trmnly.systemPrompt.add(text)
trmnly.personas.register({ id, name, emoji, summary, systemPrompt, ... })

trmnly.terminal.read({ scope })   // 'visible' | 'full'
trmnly.terminal.send(text)
trmnly.bash(cmd)                  // returns { stdout, stderr, exitCode }
trmnly.fetch(url, opts)           // gated by manifest permissions
trmnly.pwd()
trmnly.log(...)
trmnly.notify(title, body)

trmnly.browser.tabs.onLoad(fn)        // fires per browser-tab page load
trmnly.browser.network.onRequest(fn)  // fires per captured network request

Tools registered without dangerous: false default to requiring approval, so mark read-only tools explicitly. The manifest settles it per tool, and wins over the flag when both are given:

trmnly.manifest({ name: 'echo', tools: { echo: 'never', deploy: 'always' } });

never auto-approves; ask (the default) and always show the approval card every time. A tool can spell it out as { approval: 'never' } too. The Plugins panel badges each declared tool auto or ask, so you can see what a plugin approved itself for without reading its source.

The browser event listeners need the browser-events permission — they run on every navigation/request, so the user has to opt in.

A status widget re-renders every intervalMs milliseconds — every 5000 if you leave it out, and never more often than every 500. Plugins written for older builds may pass refresh in seconds instead; that still works, and when both are given intervalMs wins.

The familiar console.log works too — it routes through trmnly.log.

Permissions

Plugins declare what they need in the manifest — shell (for trmnly.bash), a network host allowlist (for trmnly.fetch, suffix-matched), terminal, pwd, notifications, and browser events. You're prompted to grant the request when the plugin first loads; without a grant the calls fail closed. The grant is pinned to a hash of the plugin file, so editing (or swapping) the file triggers a re-confirmation. The Plugins panel has a permissions inspector for each loaded plugin.

A plugin that crashes repeatedly is quarantined — the runtime stops reloading it until you hit "Reload" explicitly. The Plugins panel surfaces both the quarantine badge and the last error message.

Failures are reported rather than swallowed, which is what feeds that count: a plugin whose file throws while loading keeps the error on its row, and a tool that throws hands the agent a failed call rather than an empty success it would have to guess about. A successful call clears the run, so an occasional error never accumulates into quarantine. A quarantined plugin's tools — and those of a plugin still waiting on its permission grant — answer with the reason instead of running.

Plugins vs MCP

You can also point at any MCP server from the same Plugins panel — it appears as a remote tool source. Useful for sharing tools across editors (Claude Desktop, etc.). For TRMNLY-only tools, a plugin is simpler.

What plugins can't do

  • Touch arbitrary disk paths — file ops go through the agent's gated tools
  • Read other plugins' state — each plugin gets its own JS context
  • Persist data between reloads without using trmnly.bash to write a file (intentional, to keep plugin storage explicit)