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.bashto write a file (intentional, to keep plugin storage explicit)