All pages
Lesson 8.2 · Make it yours · 12 min
Plugins
Add tools, status pills and sidebar views in JavaScript.
After this lesson, you can write a JavaScript plugin that gives the agent a new tool and puts a live status pill in the window. You'll also know how to grant it permissions, reload it as you edit, and recover it when it breaks.
Time: 12 minutes · Works on: macOS app
What a plugin can add
A plugin is one .js file in your plugins folder. Each one runs in its own isolated JavaScript context and can add:
- tools the agent can call,
- status widgets that render text in the strip above the right sidebar,
- sidebar views under the Plugins tab,
- text for the agent's system prompt, and
- personas: an alternate prompt together with a tool allowlist.
Plugins run on the Mac only. To give tools to an agent outside TRMNLY, use the MCP server instead.
Find the Plugins tab
- Press
⌘⇧\to show the right sidebar if it's hidden. - Open More and choose Plugins.
- With no plugins installed, the tab shows Open plugins folder. Press it to open the folder in Finder. It's the
pluginsfolder inside TRMNLY's Application Support folder.
TRMNLY leaves a sample there named example.js.template. Rename it to example.js to try it, or read it for the shape of each call.
Write a tool
In the plugins folder, create
hello.js:trmnly.manifest({ name: 'hello', description: 'Greets people.', }); trmnly.tools.register({ name: 'say_hello', description: 'Greet a person by name.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'], }, execute: (input) => 'Hello, ' + input.name + '!', dangerous: false, });In the Plugins tab, press Reload all. The plugin appears under Installed with its description.
In the Agent tab, ask: "Use say_hello to greet Ada." The agent calls your tool and gets the result.
A tool registered without dangerous: false needs approval every time. That's the safe default, so set dangerous: false only on tools that read and change nothing. The manifest can also settle it per tool. tools: { say_hello: 'never' } runs it without asking, while 'ask' and 'always' show the approval card every time. The Plugins tab badges each declared tool auto or ask, so you can see what a plugin approved for itself.
Add a status widget
Add this to hello.js:
trmnly.manifest({
name: 'hello',
description: 'Greets people and shows the git branch.',
permissions: { shell: true },
});
trmnly.statusLine.add({
id: 'git-branch',
intervalMs: 5000,
render: () => {
const r = trmnly.bash('git branch --show-current 2>/dev/null');
return r.exit === 0 && r.stdout.trim() ? '🌿 ' + r.stdout.trim() : '';
},
});
Keep only one trmnly.manifest call per file. Replace the earlier one rather than adding a second.
- Press Reload on the plugin's row.
- The row shows Permissions need review, because the plugin now asks for
shell. Press Review…, read what it asks for, and press Allow requested. Save custom grants only the lines you leave ticked, and Deny grants nothing. - The branch name appears in the status strip and refreshes every five seconds.
trmnly.bash returns stdout, stderr and exit. A widget re-renders every intervalMs milliseconds, never more often than every 500.
Permissions
Everything that reaches outside the plugin is off until the manifest asks for it and you grant it:
shellallowstrmnly.bash.network: { hosts: ['api.github.com'] }allowstrmnly.fetchto those hosts. A host also covers its subdomains.terminalallowstrmnly.terminal.readandtrmnly.terminal.send.pwdallowstrmnly.pwd, which reveals the project path.notificationsallowstrmnly.notify.browserEventsallows listening to page loads and network requests in the built-in browser.
A grant is tied to a hash of the file. Edit the file and you're asked again, so a plugin can't quietly change what it does after you approved it. Edit… changes a grant and Revoke removes it.
When a plugin breaks
- An error while loading stays on the plugin's row in red, so you can read it.
- A tool that throws hands the agent a failed call, not an empty success.
- A plugin that keeps failing is marked Quarantined and stops reloading on its own. Fix the file, then press Reload on its row.
console.log works and goes to TRMNLY's log. A plugin can't read other plugins' state, and it can't touch files except through trmnly.bash.
Check yourself
- Your
say_hellotool shows under Installed, and the agent can call it. - The status strip shows your branch after you grant
shell. - Edit the file, reload, and see the permission review come back.
Go further
- Plugins: the full API, including sidebar views, personas and browser events.
- The MCP server: sharing TRMNLY's tools with other agents.
- Safety and approvals: how approval works for plugin tools and built-in ones.