Plugins

Documentation in progress

Some sections are still incomplete.

A plugin is a program of its own that adds a panel to the right sidebar. ThinkTerm starts it, talks to it, and draws what it sends — in the desktop window and in a browser alike — but none of its code runs inside ThinkTerm. A plugin that crashes takes its own panel with it, and nothing else.

Snippets, described in Files and Notes, is a plugin too. It is built in, and it uses the same interface as one you install.

Where a plugin shows up

Only in the right sidebar. A plugin with a panel is offered in the sidebar's selector under its own name, beside Files, Notes and Snippets, and listed in Settings › Sidebar & Plugins. It adds no commands, no menu items and no notifications of its own, and nothing for the command palette. The one key that concerns a plugin is an action you can bind to give its panel the keyboard — see Typing in a panel and Keyboard and Commands.

A panel with more to show than the sidebar has room for can open a wider view to the left of it, as wide as you drag it. Where there is no room for one — a narrow window, a phone — the plugin fits what it would have shown there into the panel itself.

The panel looks the same in a browser as on the desktop, because both draw it with the same code and in ThinkTerm's own colours. A browser uses the plugins on the machine whose server served its page, not the ones on the device the browser runs on — so a headless host shows its own plugins, and the server packages ship the plugin server for that reason. See Web.

Typing in a panel

A panel can have fields to type in: one line, several lines, or a secret that shows dots. ThinkTerm draws and edits them itself, in its own font and colours, so input methods, selection and the clipboard work in them as anywhere else in the window. A secret field cannot be copied or cut from, and its text reaches the plugin only when you submit it.

The keyboard stays with the terminal until you give it to a panel. Pressing in a field gives it the keyboard there; a press anywhere else in the panel does not, so a click is only a click. On the desktop you can also bind a key to a panel with FocusPluginPanel. It opens the right sidebar on that panel and puts the keyboard in its first field, and pressing the key again gives the keyboard back:

config.keys = {
  { key = 'S', mods = 'CMD|SHIFT', action = wezterm.action.FocusPluginPanel 'stocks' },
}

A browser has no such key: there a panel gets the keyboard through its fields.

While a panel has the keyboard, the plugin hears the few keys it asked for, such as the arrows, and what its fields hold. A key pressed with Ctrl, Alt or Command never reaches it. Escape, or a click on the terminal, gives the keyboard back; Tab moves it between the panel's fields. If a panel loses the keyboard without you taking it — its plugin stopped, say — what you type next goes nowhere until you press Escape or click, and does not reach the terminal.

Installing and removing

A plugin is a directory holding a plugin.toml and the program it runs. Installing one means putting that directory in the plugins directory:

System	Plugins directory
macOS	~/Library/Application Support/ThinkTerm/plugins
Linux	~/.local/share/ThinkTerm/plugins
Windows	%APPDATA%\ThinkTerm\plugins

There is no install step and no restart. ThinkTerm notices a new plugin the next time it looks: when Settings › Sidebar & Plugins opens, or when you run thinkterm plugin list. Deleting the directory removes it.

A plugin it has not seen before is new, and nothing of it runs until you allow it. Settings › Sidebar & Plugins shows it as New: it does not run until you allow it, with an Allow button, on the desktop and in a browser alike; thinkterm plugin enable <id> allows it from a shell, and thinkterm plugin list shows its state as new. Until then its panel is not offered, calls to it are refused, and its program is not started — not even with Keep alive.

ThinkTerm remembers the directory you allowed the plugin in. The plugin is new again, and a copy that was running is stopped, when it is moved, when a link is pointed at another copy, when another plugin takes its id, or when its manifest gives it another id. Updating a plugin in place, or rebuilding one you work on through a symbolic link, asks nothing again. In plugins.json, beside the plugins directory, a plugin that is waiting is written as off, so a ThinkTerm older than this one, sharing the file, does not run it either. One that is off only because it was somewhere else comes back on when it is back where you allowed it; one you turned off yourself stays off.

Nothing downloads or installs a plugin for you, and there is no catalogue to pick one from in the app. Every plugin on the machine is one somebody copied there. People who share plugins put them on GitHub under the topic thinkterm-plugin, with the plugin.toml at the root of the repository, so that cloning it into the plugins directory is the whole install. A plugin is a program that runs as you: copy only one you trust, however it reached you.

The command line

thinkterm plugin looks at plugins and drives them from a shell:

Command	What it does
thinkterm plugin list	Every plugin, its state (new while it waits to be allowed) and its version
thinkterm plugin enable <id>	Turns a plugin on; for a new one, it also allows it to run
thinkterm plugin disable <id>	Turns a plugin off
thinkterm plugin reload [<id>]	Stops a plugin and reads its manifest again; every installed plugin when no id is given
thinkterm plugin call <id> <json>	Sends a plugin a call and prints its answer
thinkterm plugin dir	Prints the plugins directory

reload also clears a plugin that has crashed or failed, so it can be tried again. The same switches, a Reload button and a way to open the plugins folder are on Settings › Sidebar & Plugins.

How plugins run

Plugins are not run by the window. They run under thinkterm-plugin-server, a small process apart from the GUI and from the session server, which the desktop, a browser and the command line all talk to. One runs per user on each machine. It starts when something first needs a plugin, and exits 30 seconds after the last thing using it goes, stopping every plugin with it.

Each installed plugin you have allowed is then a process of its own, started the first time it is used — a panel coming on show, or a call from the command line. A plugin that exits unexpectedly is shown as stopped and started again the next time it is used; one that crashes three times within a minute is marked failed and left alone until you reload it or its files change. When its program changes on disk, ThinkTerm restarts it before its next use.

How long a plugin runs unused

A plugin is in use while one of its panels is on show anywhere, in a window or a browser, or while a call to it is waiting for an answer. Once it is not, how long its program runs on depends on its background mode:

Setting	Starts	Stops
Keep alive	with ThinkTerm on the machine	when ThinkTerm on the machine is gone
On demand (the default)	when it is used	2 minutes after it was last used
Stop after use	when it is used	10 seconds after it was last used

A plugin's manifest says which it needs. The menu beside each plugin on Settings › Sidebar & Plugins overrides it per plugin, on the desktop and in the browser; the menu marks the one the manifest asked for as The plugin's default.

The trade-off is between a panel that is ready the moment you open it and a program that is not running while you are not looking. Keep alive suits a plugin that watches something for you; it is also the only mode in which ThinkTerm starts a plugin without being asked, and even then only one you have allowed. A plugin kept alive that stops by itself is started again after two seconds, until it is marked failed.

"ThinkTerm on the machine" means the desktop app or the session server, whichever is running. On a host with no desktop it is the session server, so a plugin kept alive there runs for as long as that server does. Each machine keeps its own choice: the same plugin can be kept alive on a server and run on demand on a laptop.

The terminal beside a panel

A plugin is told how thinkterm cli reaches the terminal beside its panel, and the program it runs finds the thinkterm that ThinkTerm ships with in THINKTERM_CLI. With them a plugin reads what that terminal shows, lists what runs in the panes, and follows what happens in them — programs and commands finishing, titles, status reports — using the command line described in Command Line. A terminal on another machine is reached through the ThinkTerm that shows it, which passes on what is asked. The terminal is the pane in focus, and the plugin is told of a new one as soon as you move to it; its directory, and whether it is on another machine, follow once that pane has said where it is.

A terminal on another machine

A panel belongs to the terminal beside it — the pane in focus in its window — and a plugin is told that terminal's directory. When that terminal runs on another machine reached over SSH, the plugin itself still runs here, on this machine. What it wants done there it asks ThinkTerm to do: run a program, read a file, or look at what is at a path. ThinkTerm does it over the same connection the Files panel uses, as you.

Those asks are limited in ways worth knowing:

• They reach only the machine of the terminal beside the plugin's panel, and only while that terminal is still there. One made for a machine the terminal has left fails.
• ThinkTerm connects to a machine only once you have let it, in Files or with the button the panel shows in place of its contents. Until then every ask fails. Letting it in Files counts for plugins too. A host whose Connect Files automatically is on is let by itself when Files is on show beside a terminal on it; a plugin's panel on show does not do that on its own.
• A program run there is stopped after 20 seconds.

This is a desktop feature. A panel in a browser does not reach other machines this way.

What a plugin can do

A plugin is a program you put on the machine, and it runs as you, with your permissions. Nothing of it runs before you allow it, so a plugin that turns up in the plugins directory without you is only listed. Once allowed, ThinkTerm shows nothing of a plugin outside the sidebar, but that does not stop the program itself from reading your files, using the network, or running other programs: only a sandbox would, and there is none. Install one the way you would install any other program.

Remote asks extend that to the machines you reach over SSH, so a plugin you trust here is a plugin you trust on every host whose terminal sits beside its panel. The limits above narrow when it can reach them, not what it can do once it has. Likewise a plugin can read everything the terminal beside its panel shows, as anyone running thinkterm cli as you can.

The plugins in ThinkTerm's source

ThinkTerm's source carries three plugins under plugins/. They are not part of the downloads: each is built with Cargo and installed by copying its plugin.toml and program into a directory of its own in the plugins directory.

• Diff (diff) shows the changes in the git repository of the terminal beside it since the last commit, the way GitHub Desktop does: the changed files in the panel, and the picked file's lines in the wider view, each changed line marked. A field above the files narrows them to those whose path holds the text, whatever its case; with the keyboard in the panel, Up and Down pick the file before or after, and Return in the field picks the first one left. It runs git every two seconds while a panel is on show, less often in a repository git is slow over, and without the programs a repository's configuration can name for it — an fsmonitor, an external diff, a text converter. Beside a terminal on another machine it has git run there through ThinkTerm.
• Stocks (stocks) is a watchlist of quotes from Yahoo Finance, with each symbol's day as a line and a chart of the one picked. A symbol is added by typing it in the field at the top of the panel and pressing Return; with the keyboard in the panel, Up and Down pick the symbol before or after. Yahoo's chart API is not an official one, and may refuse or change without notice.
• Text Tools (text-tools), in plugins/example, is there as a starting point for writing one. It answers two calls from the command line, decode and uuid, and has a panel that decodes what you type in it — a JWT, a Unix time, URL encoding or Base64 — or, with Decode from the terminal, the lowest line on the terminal beside it that decodes, and shows the result wrapped over as many lines as fit.

Writing a plugin

A plugin's program talks to ThinkTerm over standard input and output, one line of JSON at a time. A panel is drawn by hand: the plugin sends a list of rectangles, text, lines and filled areas, and the places a click reaches it, and ThinkTerm draws them. A text can ask to be wrapped: it is then broken into as many lines as its box is tall, the desktop and a browser breaking it alike, and ends in an ellipsis where it does not all fit. There are no widgets.

The Rust crate thinkterm-plugin-sdk implements the protocol, and the plugins above use it. The manifest, the messages, the panel items and the limits are documented in full in docs/thinkterm/plugins.md in ThinkTerm's repository. While working on one, link your source directory into the plugins directory and rebuild; anything the program writes to standard error goes to the plugin server's log.

Related

• Files and Notes — the other right-hand panels, Snippets among them
• Web — the browser, which shows the same panels
• Remote — the connections a plugin's asks travel over
• Command Line — the rest of the thinkterm subcommands