Plugins

Install plugins from git and pin them in plugins.lock. Write a plugin in minutes with tuios plugins new. Run herdr plugins unchanged, and native plugins that say which grants they need.

A plugin adds actions, panes, startup services, event hooks and dock cells to tuios. tuios runs two kinds:

  • herdr plugins: a folder with a herdr-plugin.toml, in the format of herdr 0.9.5. tuios runs them unchanged.
  • Native plugins Added in v0.11.0: a folder with a tuios-plugin.toml. A native plugin says which grants it needs, and the daemon holds it to them. It runs only after you approve it on this machine.

tuios plugins install Added in v0.11.0 gets a plugin with git, shows what it runs, builds it and pins its commit in plugins.lock. The daemon never fetches and never builds.

A plugin is not sandboxed

An enabled plugin runs with your rights. It can read your files, change your dotfiles and run any program. Grants limit what a plugin can ask of tuios. They do not stop a program that tries to escape. Install only plugins that you trust.

A native plugin's popup over two panes. The plugin holds the read grant. It lists the panes with tuios list-windows, and its tuios send-text into the shell pane is refused: send-text needs the write grant.
A native plugin that holds read. It can list the panes. It cannot type into one.

Quickstart

Run these in a terminal outside tuios. tuios refuses install, update, uninstall, link, unlink, enable, disable, build and dev inside a tuios pane, and from a process that a plugin started.

tuios plugins install alexarthurs/herdr-sidebar/plugins/herdr-sidebar   # get, build, pin and enable
tuios plugins list                    # what tuios found, and the state of each
tuios plugins info herdr-sidebar      # what it runs, and its grants

A running daemon starts an enabled plugin at once. Without a daemon, the plugin starts with the next one.

herdr-sidebar is a file explorer in a pane. A click on a file opens its preview.

Writing a plugin

tuios plugins new NAME Unreleased makes a plugin folder that works. tuios plugins dev Unreleased runs it and reloads it when you save a file.

tuios plugins new weather      # make the folder weather, with the plugin you.weather
tuios plugins dev weather      # install it in place, reload it on each change, until Ctrl-C
Made the plugin you.weather in weather.
Try it: tuios plugins dev weather

The folder holds four files:

FileWhat it holds
tuios-plugin.tomlThe manifest. It asks for the ui grant and names one action, Say hello
hello.shThe script that the action runs. It shows a notification
README.mdHow to try, check and install the plugin
.github/workflows/plugin.ymlA GitHub workflow. It runs tuios plugins check on each push, and attaches the plugin to the release of each tag

Open the command palette in tuios and choose weather: Say hello. --id sets another plugin id. The default is you.NAME.

dev asks once when it starts. After that it gives the new approval for each change to the manifest, for the folder you named and nothing else. Run it from a terminal outside tuios.

To start on GitHub instead, use the template repository Gaurav-Gosain/tuios-plugin-template. It holds the same files.

Themes in a plugin Unreleased

A plugin can bring themes. Name each theme file in the manifest:

[[theme]]
file = "themes/dusk.json"

A theme file has the format on the Themes page. When the plugin is on, its themes load with your own themes. The theme picker and [appearance] theme show them. A theme file of your own in ~/.config/tuios/themes/ with the same id wins over the theme of a plugin.

tuios plugins install themes installs the themes that ship with tuios.

A screen saver in a plugin Unreleased

A plugin can bring a screen saver as a frames file. The file holds text frames with times and colours. tuios plays the file, and no program runs. A tool, such as an editor for ASCII art, can write the file.

[[saver]]
id = "blink"
file = "savers/blink.txt"

To use it, set effect = "plugin/ID/SAVER" in [screensaver], such as plugin/you.faces/blink. tuios plugins check reads each frames file and names the line that is wrong.

tuios-saver 1
size 7 3
fps 4
color e #5fd7ff
color m bright_red

frame
 o   o
   ^
 \___/
colors
 e   e

 mmmmm

frame 300
 -   -
   ^
 \___/
  • The first line is tuios-saver 1.
  • size COLS ROWS comes once, before the first frame. The maximum is 400 by 200.
  • fps N sets the time of each frame after it, from 1 to 50. The default is 10.
  • color LETTER COLOUR gives a letter a colour: #rrggbb, or an ANSI name from black to bright_white. An ANSI name follows the theme.
  • frame starts a frame of ROWS lines. frame MS shows that frame for MS milliseconds.
  • colors after a frame gives a letter for each cell, in ROWS lines. A space keeps the default colour.
  • A line that starts with # outside a frame is a comment.
  • A file has at most 2,000 frames and 4 MB. The drawn frames can have at most 16 MB.
  • The file must be in the plugin folder. A link to a file outside the folder stops the plugin from loading.
  • tuios puts the frames in the centre of the screen and loops them until you press a key or move the mouse.

A plugin that has only themes and savers runs no program and asks for no grant. It needs no approval after the install.

Checking a plugin Unreleased

tuios plugins check [PATH] reads a plugin folder as tuios does. It runs nothing and needs no daemon. It prints each problem and warning, and exits 1 when the plugin cannot load:

you.weather 0.1.0 (tuios plugin)
  actions  hello (1)
warning: schema is an old name. Use api = 1
The plugin loads.
the plugin cannot load: unknown key process.bogus in tuios-plugin.toml. Check the spelling. If the plugin needs a newer tuios, run tuios update

Run it in your CI. The workflow from tuios plugins new does that.

Publishing a plugin

A plugin is a git repository. People install it with tuios plugins install OWNER/REPO, and tuios plugins update follows its default branch. To publish a version, push a tag such as v0.1.0. People install it with tuios plugins install OWNER/REPO@v0.1.0.

Keep version in the manifest in step with the tag. Change the manifest only when you must: a new grant or a new command asks every person again.

Installing a plugin

tuios plugins install pr-status                   # a plugin of the tuios release
tuios plugins install owner/repo                  # github.com, the default branch
tuios plugins install owner/repo@v0.3             # a tag, a branch or a full commit
tuios plugins install owner/repo/plugins/notes    # the plugin folder, when it is not the top of the repository
tuios plugins install https://gitlab.com/a/b.git@main
tuios plugins install ./my-plugin                 # a folder on this machine, used in place

The manifest must be at the top of the folder you name. When a repository keeps its plugin in a subfolder, name that folder, or pass --subdir. A git URL can be https://, ssh://, git@host:path or file://. Plain http:// is refused. You need git on your PATH.

tuios gets the source into a new folder, then shows the plan and asks:

Install example.panes 0.2.0 (tuios plugin)
  from    https://github.com/example/panes @ v0.2.0 = 6e30e96b68fb
  folder  ~/.local/share/tuios/plugins/example.panes/6e30e96b68fb-dma6hbj1j76h

Build commands (run now, in that folder, with your rights):
  go build -o bin/panes .

Runs when enabled, outside every pane, with your rights:
  panes    list (popup) (1)

It can call tuios with these grants, in every session:
  read   Reads every session and pane on this machine.
Grants are not a sandbox. The plugin can read your files and run any program as you.
tuios enables the plugin after the install.
FlagDoes
-y, --yesInstall without the question
--ref REFThe branch, tag or full commit. The same as SOURCE@REF
--subdir DIRThe plugin folder in a repository given by URL
--no-enableInstall and build, but leave the plugin off
--no-buildDo not run the build commands
--replaceReplace an installed plugin with the same id from another source
--grant adminGive the admin grant to a native plugin that asks for it. See Grants

Each install builds into a new folder. When the build fails, or you stop it, nothing that runs changes: the plugin keeps its old folder and its old pin. After a good build, tuios writes the pin, and the daemon restarts the plugin from the new folder. tuios keeps the new folder and the one before it, and removes older ones.

A plugin that is installed from the same source and ref already: install tells you to run update. To follow another ref, run tuios plugins install SOURCE@REF.

Plugins of the tuios release Unreleased

Each tuios release carries its own plugins:

NameWhat it does
ovnfsOpens copy-on-write checkouts of a folder with ovnfs, and diffs and applies them back. See ovnfs checkouts
pr-statusShows the pull request and CI state of the focused pane's folder in the dock
sketchDraws every Mermaid diagram type in tuios mermaid and in TML panels. tuios draws eight types itself
themesAdds the themes Dusk and Paper. See Themes in a plugin

tuios plugins install pr-status takes the plugin from the release of the tuios that runs. It needs no git and no build. tuios checks each file against the checksums.txt of the release, and plugins.lock pins the version and a hash of the files. On another machine, tuios plugins install gets the same files or nothing.

ovnfs checkouts

An ovnfs checkout is a copy-on-write view of a folder. It opens in about a second at any size and copies nothing. Work in it, then apply the changes back. The plugin needs ovnfs 0.4.0 or newer and jq on your PATH. With an older ovnfs it says so and does nothing else, and ovnfs update brings ovnfs up to date.

go install github.com/stencil-hq/ovnfs@latest
tuios plugins install ovnfs

In the command palette:

EntryWhat it does
ovnfs: New checkout hereOpens a checkout of the focused pane's folder, and a pane with your shell in it
ovnfs: CheckoutsLists the checkouts with their changes and idle time. Choose one to diff, apply, apply to a branch, open a pane in it, attach it to a host or remove it. p prunes
ovnfs: DiffShows what the checkout changed
ovnfs: ApplyShows a dry run, then merges the changes into the folder when you type yes
ovnfs: Apply to a branchMakes a branch in the folder's repository from the checkout's commits
ovnfs: Attach to a hostMakes the checkout appear on another machine over ssh. It prints the line that opens a pane there, and the ovnfs push line that lets the checkout work there without this machine
  • When a pane the plugin opened closes and its checkout has changes, the plugin says so, and the dock shows ovnfs N to review. It never applies by itself.
  • When TUIOS removes a worktree, the plugin removes the checkouts of that worktree. It takes a snapshot of a checkout with changes first, and keeps the snapshots, so ovnfs new --from SNAP opens the work again. Removing a checkout from the list keeps its snapshots too.
  • tuios ship leaves the remotes of an ovnfs checkout out of where it pushes.
  • The plugin holds the ui grant. Its panes hold no grant. ovnfs runs with your rights: it is not a sandbox.

tuios plugins update moves these plugins to the release of the tuios that runs. tuios update does that after it installs a new tuios. When a package manager updates tuios, run tuios plugins update after it. A tuios that you built yourself has no release. Install the plugin from its folder: tuios plugins install Gaurav-Gosain/tuios/plugins/pr-status.

plugins.lock Added in v0.11.0

plugins.lock sits beside config.toml. It holds the source, the ref and the exact commit of each plugin you installed:

version = 1

[[plugin]]
id = 'example.panes'
format = 'tuios'
source = 'https://github.com/example/panes'
ref = 'v0.2.0'
commit = '6e30e96b68fb6c1b2d0d6a1e0e7f2c7e3b9a1d4f'
approved = 'sha256:f05d82adf886ed12f6833850faaa3c346da854c73547f4517081a43a9f5669fe'
grants = ['read']

approved is a hash of what the plugin runs and asks for. A state file in the data folder names the folder that runs on this machine. The lock does not, so you can keep plugins.lock in your dotfiles and share it between machines.

On a new machine with your config folder, install everything the lock pins:

tuios plugins install          # each plugin in plugins.lock, at its commit

This does not enable a plugin. [plugins] enabled in config.toml does that. A native plugin from the lock also waits for your approval on each machine. With --yes you trust the person who wrote the lock file. tuios still asks, also with --yes, when a manifest differs from the one the lock approved. The hash keeps the question honest. It is not a sandbox.

Updating a plugin Unreleased

tuios plugins update [ID...] moves each installed plugin to the newest commit of the ref it follows. Give ids to update only those. tuios shows the new commits, the build commands and what the plugin runs, and asks. --yes skips the question.

tuios asks again, also with --yes, in three cases. With no terminal, tuios refuses these updates.

  • What the plugin runs or asks for changes. tuios shows the lines that change.
  • The history of the branch was rewritten.
  • The tag that the plugin follows points to a different commit.

A change to the code alone does not ask again with --yes. Read the commits.

  • When the plugin's folder did not change, tuios says up to date.
  • The update builds into a new folder, so a failed build changes nothing that runs. The daemon then restarts the plugin.
  • An open plugin pane keeps its old folder until you open it again. A plugin that is off stays off.
  • --check shows the same facts and changes nothing.
  • When tuios cannot reach a source, that plugin stays at its commit. tuios goes on to the next one, and the command exits 3.
  • A plugin from a folder has no update. A plugin pinned to a commit stays there.

Removing a plugin Added in v0.11.1

tuios plugins uninstall ID undoes the install. It disables the plugin, stops its processes and closes its panes. Then it removes the plugin from plugins.lock, removes its approval, and removes $XDG_DATA_HOME/tuios/plugins/<id>/. --yes skips the question.

  • ID can also be the source you installed from, such as owner/repo.
  • tuios keeps the config and state folders of the plugin. For a plugin installed from a local folder, tuios keeps that folder.
  • tuios refuses a plugin that it did not install. For a linked folder or a folder in [plugins] dirs, use tuios plugins unlink ID.

Approving a native plugin Added in v0.11.0

A native plugin runs only after you approve it on this machine. tuios plugins install shows the plan and asks you in the terminal. Your yes approves the plugin. A native plugin that comes another way waits for you:

  • from plugins.lock on another machine,
  • from tuios plugins link DIR, then tuios plugins enable ID,
  • from a plugin folder.

tuios plugins install asks a running tuios daemon to confirm that the command runs outside every pane. With no daemon to ask, the plugin also waits for you.

tuios plugins list shows a plugin that waits as waiting for approval, and a plugin you denied as denied. The last column gives the reason for the state:

ID             STATE                 FROM     VERSION  SOURCE                            NAME   REASON
example.notes  waiting for approval  config   0.2.0                                      Notes  example.notes waits for your approval on this machine. Allow it in tuios, or run tuios plugins approve example.notes
example.panes  on                    managed  0.2.0    https://github.com/example/panes  Panes

When you attach, tuios asks in a dialog. The dialog shows the plugin's source, what it runs and each grant in plain words. A grant that can act as you, such as write, shows in the warning colour.

The plugin approval dialog. It asks: Allow the plugin Notes? It names the folder the plugin comes from, the pane it runs, and its read and write grants. A field waits for the word allow. Below are Allow, Deny and Not now, with Not now selected.
A linked plugin asks for read and write. Type allow and press Enter to run it.
  • To allow the plugin, type allow in the field and press Enter. For a plugin that asks for admin, type admin. No single key or click allows a plugin.
  • Deny keeps the plugin off. tuios plugins list then shows denied. A click on Deny asks for a second click.
  • Not now closes the dialog. The plugin keeps waiting. Enter and Esc start on Not now.
  • The dialog ignores keys and clicks for half a second after it opens. Text that you type into a pane at that moment answers nothing.
  • Only you can answer. A key that a tape or send-keys sends does not answer the dialog.

tuios plugins approve ID asks the same question in a terminal. --deny denies the plugin, --grant admin gives a plugin the admin it asks for, and --yes answers without the question. The command needs a running tuios daemon, which confirms that the command runs outside every pane.

The approval covers the manifest and the files that its commands name. When the manifest changes, tuios asks again.

Turning plugins on and off

Nothing runs until you enable it. To find and list a plugin runs none of its code.

tuios plugins enable example.panes     # add it to [plugins] enabled, start it now
tuios plugins disable example.panes    # remove it, and stop its processes
tuios plugins link ~/src/my-plugin     # use a folder in place, off until you enable it
tuios plugins unlink my-plugin         # stop using the folder, and close the plugin's panes

A change to config.toml that removes a plugin from enabled applies at once. A change that adds one waits for tuios config apply or a daemon restart.

Run these commands in a terminal outside tuios. Inside a pane they stop with a message:

tuios plugins disable is for the person, and this command runs inside a tuios pane. Nothing was changed. Run it from a terminal outside tuios

A process that a plugin started cannot turn a plugin on or off either.

tuios looks for plugins in five places, in this order. When two places have the same id, the first wins, and plugins list shows the other with plugin_id_shadowed.

  1. The folders that [plugins] dirs names. tuios plugins link adds one.
  2. The tuios plugins folder, $XDG_CONFIG_HOME/tuios/plugins/.
  3. The plugins in plugins.lock. plugins list shows them as managed.
  4. herdr's registry, ~/.config/herdr/plugins.json.
  5. herdr's managed checkouts, ~/.config/herdr/plugins/github/*.

tuios only reads herdr's files. A plugin that herdr installed stays off in tuios until you enable it here.

Running a plugin

EntryWhen it runs
BuildOnly at tuios plugins install, tuios plugins update or tuios plugins build ID. tuios shows each command first
StartupWhen the daemon starts, and when you enable the plugin
ActionFrom the command palette, a command key, or tuios plugins run ID ACTION
PaneFrom the command palette, or tuios plugins open ID PANE
EventEach time an event that the entry names happens, such as a focus

A command is an argv list. No shell reads it. It runs in the plugin folder, outside every pane, as your user. tuios plugins log shows the last runs, with exit codes and the start of their output.

To put an action on a key, add a command key of type plugin_action:

[[keybindings.command]]
key = "prefix+alt+l"
type = "plugin_action"
command = "example.layout.apply"
description = "Apply layout"

What a plugin costs Unreleased

tuios plugins stats shows each plugin's processes and memory now, and its runs and run time since the daemon started. It needs a running daemon. macOS shows no memory. --json prints the same data for a script. From a pane, the command needs the admin grant.

Native plugins

A native plugin is a folder with tuios-plugin.toml:

api = 1
id = "example.panes"
name = "Panes"
version = "0.2.0"
description = "List the panes of every session."
min_tuios = "0.11.0"             # optional
platforms = ["linux", "macos"]

[permissions]
grants = ["read"]                # read, write, fan, ui or admin

[[build]]
command = ["go", "build", "-o", "bin/panes", "."]

[[process]]
id = "list"
run = "pane"                     # action, pane, event or startup
title = "Panes"
placement = "popup"
width = 100
height = 22
command = ["bin/panes"]
KeyRequiredWhat it holds
apiyesThe plugin API version. Write 1. schema = 1 still works, and tuios plugins check warns
idyesLetters, digits, ., - and _. Use yourname.plugin
nameyesThe name people see
versionyesThe version of the plugin, such as 0.1.0
descriptionnoOne sentence
min_tuiosnoThe oldest tuios that runs this plugin
platformsnolinux, macos, windows. Leave it out for every platform
[permissions] grantsnoThe grants the plugin asks for. Leave it out for none
[[build]] commandnoA command that install runs in the plugin folder
[[process]]noA program that tuios runs. See below
[[theme]] filenoA theme file in the plugin folder. See Themes in a plugin
[[saver]]noid and file, a frames file in the plugin folder. See A screen saver in a plugin
[[cell]]noA dock cell. See Showing something
[herdr] manifestnoTake the commands from a herdr-plugin.toml

tuios refuses a key it does not know, so a typo fails at once. A manifest that uses a newer api, key, grant or run value fails with plugin_requires_newer_tuios, and tuios tells you to run tuios update. tuios plugins info ID shows the grants the plugin asks for and the ones it holds.

A [[process]] has id, run and command. run says when it runs:

runWhen it runsOther keysCost when idle
actionWhen you run it from the palette, a key or tuios plugins runtitle, description, contextsNone
paneWhen you open it from the palette or tuios plugins opentitle, description, placement, width, heightNone
event UnreleasedEach time an event in on happens. The command runs and exitsonNone. One run each time the event happens
startupOnce, when the daemon starts or you enable the pluginA process for as long as it runs

placement is popup, overlay, split, tab or zoomed. A program with a / in its name is found from the plugin folder. A program without one is found on PATH.

Use an action, a pane or an event when you can. They cost nothing until you use them or the event happens. A startup process stays in memory for as long as it runs. Use one only when the plugin must watch something all the time.

tuios plugins list shows example.panes as on and managed, at version 0.2.0. tuios plugins info example.panes shows its manifest, name, platforms, the grants it asks for and holds (read), and its popup pane.
plugins list and plugins info for an installed native plugin.

Events

An event process names its events in on:

[[process]]
id = "focus"
run = "event"
on = ["pane.focused", "tab.focused", "workspace.focused"]
command = ["sh", "pr-status.sh"]
KindEvents
panepane.created, pane.closed, pane.focused, pane.moved, pane.exited, pane.agent_detected, pane.agent_status_changed
tabtab.created, tab.closed, tab.renamed, tab.moved, tab.focused
workspaceworkspace.created, workspace.updated, workspace.closed, workspace.renamed, workspace.moved, workspace.reordered, workspace.focused
worktreeworktree.created, worktree.opened, worktree.removed

A plugin runs at most 20 event commands in 10 seconds. tuios drops the rest and logs them. tuios stops an action or an event command after 10 minutes.

The environment

Every process of a native plugin gets these variables:

VariableValue
TUIOS_BINThe tuios binary that runs the plugin. Use it instead of tuios, which depends on PATH
TUIOS_SOCKETThe socket of that daemon. The command line reads it
TUIOS_PLUGIN_ROOTThe plugin folder
TUIOS_PLUGIN_CONFIG_DIRA folder for the plugin's settings. An update keeps it
TUIOS_PLUGIN_STATE_DIRA folder for the plugin's data. An update keeps it
TUIOS_PLUGIN_ENTRYThe id of the [[process]], for an action or a pane
TUIOS_PLUGIN_EVENTThe event that ran an event process, such as pane.focused
TUIOS_PLUGIN_EVENT_JSONThe event as JSON
TUIOS_PLUGIN_SESSIONThe session of the focused pane. -s takes it
TUIOS_PLUGIN_PANEThe focused pane. -w takes it
TUIOS_PLUGIN_CWDThe folder of the focused pane
TUIOS_PLUGIN_CONTEXT_JSONAll of the context above as JSON, with the agent and the selected text
TUIOS_PLUGIN_ID, TUIOS_PLUGIN_TOKENWho the process is. A pane of the plugin does not get these. Do not print the token

A background process runs in the plugin folder, with no terminal and stdin closed. tuios keeps the first 64 KiB of its output. tuios plugins log shows it. A pane starts in the plugin folder too.

To call tuios, use the command line. "$TUIOS_BIN" list-verbs lists every verb of the JSON socket, and "$TUIOS_BIN" call VERB calls one. Add --json to read a listing in a script.

"$TUIOS_BIN" list-agents -s "$TUIOS_PLUGIN_SESSION" --json
"$TUIOS_BIN" capture-pane -s "$TUIOS_PLUGIN_SESSION" -w "$TUIOS_PLUGIN_PANE"

Showing something Unreleased

A plugin with the ui grant shows text in the dock and sends notifications. Name each cell in the manifest:

[permissions]
grants = ["ui"]

[[cell]]
id = "status"
side = "right"    # left, center or right

Set the cell from any command of the plugin, then let the command exit. The daemon keeps the text, so no process waits.

"$TUIOS_BIN" plugin-cell set status "CI ok" --action open
"$TUIOS_BIN" plugin-cell clear status
"$TUIOS_BIN" plugin-notify "The build failed" --level error
  • --action names an action of the plugin. A click on the cell runs it.
  • A cell is one line of at most 512 bytes. SGR colour stays. tuios removes other control sequences, and cuts the cell to 24 cells on the dock.
  • A plugin can name 8 cells. It can change cells and send notifications 8 times a second.
  • tuios puts the plugin's name before a notification. The level is info, warning or error.
  • The cells go when the plugin stops. A new daemon starts with no cells. Set them again from a startup process or the next action.
  • To place a cell yourself, add plugin/ID/CELL to a list in [dock].

"$TUIOS_BIN" tml show FILE -s "$TUIOS_PLUGIN_SESSION" opens a panel. With ui, a plugin opens, changes and closes its own panels. Only a plugin's process can set a cell or send a notification. From a pane or a shell, the commands fail.

A herdr plugin with grants

To give a herdr plugin grants without changing it, add a tuios-plugin.toml beside its herdr-plugin.toml that points at it:

api = 1
id = "herdr-sidebar"

[herdr]
manifest = "herdr-plugin.toml"

[permissions]
grants = ["read", "write"]

The commands, the name and the version come from the herdr manifest. The native file adds only the grants, and it may not list [[build]] or [[process]] of its own. The two ids must match. In a folder with both files and no [herdr] table, tuios-plugin.toml wins.

Grants

A plugin's processes call tuios to read panes, type into them and open new ones. Each call is checked against the plugin's grants, as a call from a pane is checked against the pane's grants.

GrantLets the plugin
noneDo what every pane may do. A plugin that only opens a pane needs no grant
readList sessions and panes, read a pane's screen, and follow events in every session
writeType into your panes and shells, so it can run commands as you. It stops at an agent's approval prompt
fanStart agents with fan and start-agent
uiShow dock cells, panels and notifications. It cannot type into or read a pane
adminEverything else. It implies read, write and fan, never respond. It needs your approval on this machine
respondRefused. Only you answer an agent's prompt
  • A native plugin holds the grants you approved on this machine, in every session. Until you approve it, it does not run.
  • A herdr plugin with no native file holds the default grants of [agents.permissions]. To give it fewer, add a native file. See A herdr plugin with grants.
  • A pane that a native plugin opens holds no more than the plugin.
  • No plugin process can act as you. It cannot enable a plugin or answer a prompt.
  • Ask for the least you need. A plugin that shows a status needs ui, not write.

A plugin with write types into a pane whatever that pane holds, your own shells included. tuios refuses its keys for a pane that waits on a prompt tuios knows of: an agent's approval that the harness reports or a screen rule finds. tuios checks again right before the Enter of send-text --submit, ask-agent and run. tuios does not know a plain question in a shell, such as read -p, sudo, rm -i or an ssh host key question. A plugin with write can answer it. A plugin cannot queue with queue-prompt or send-review.

Admin. admin reaches every pane and verb, so tuios asks more for it:

tuios plugins install owner/repo --grant admin

tuios plugins approve ID --grant admin does the same for a plugin that is already there. Without --grant admin, the install stops and says so. With it, tuios asks each tuios daemon that runs whether the command runs outside all of its panes and plugins. Every daemon must agree. tuios does not start a daemon to ask, so start tuios first. Then tuios records the approval in the state folder. plugins.lock alone never gives admin.

The approval covers the manifest and the files that the plugin's commands name as arguments, such as bin/panes or probe.sh. When one of them changes, the plugin loses admin at its next start, until you approve it again. tuios reads the approval only when you own the file and its folder, and nobody else can write them.

What this does not stop

Grants keep a plugin's mistakes, and a tool that a prompt misled, inside what you approved. They do not make a plugin safe to run. A plugin runs with your rights.

  • The build and the plugin's commands run as your user. They can read and write your files, like any program you run.
  • The admin approval does not cover files that the named files load, such as a sourced lib.sh, a Python module or node_modules. It does not cover an argument that is not a plain file name, such as sh -c "./probe.sh" or go run .. It does not cover programs on your PATH, data files, or a command that already runs.
  • tuios knows a plugin's process by its process session. A process that starts a new session with setsid leaves the plugin. So does a command run over ssh, or a process that points XDG_RUNTIME_DIR somewhere else.
  • Any program that runs as you can write the approval file, as it can write config.toml.

Install plugins that you trust, from sources you trust.

What tuios promises

  • api = 1 stays. A plugin written for api = 1 keeps working in every later tuios that reads api = 1. The manifest keys, the TUIOS_* variables, the tuios plugins commands and the JSON verbs keep their meaning.
  • New things are additions. A tuios can add a key, a grant, a run value or a variable in api = 1. It does not change what an old one means. A plugin that uses a new one sets min_tuios.
  • A removal has a warning first. A name that goes away stays as an alias for at least one minor release, and tuios plugins info shows a warning. Only a new api number removes a name.
  • An older tuios never guesses. It refuses a manifest with something it does not know, and says what to do. It does not ignore a grant.
  • Before v1.0, the rest can move. The output of tuios plugins list is for people. Use --json in a script.

Platforms

tuios runs each command of a native plugin under a small tuios process. That process leads the command's process session, and it waits until nothing the command started is left. On Linux this costs about 2.7 MB of memory for each running command, and it wakes only when a process ends. macOS has no subreaper. There, when the command has ended and something it started still runs, the process checks once a second.

On Windows and the BSDs, tuios cannot tell which process calls, so it does not run the commands of a native plugin yet. They fail with plugin_unsupported_platform. herdr plugins run there as before.

Files

PathHolds
$XDG_CONFIG_HOME/tuios/plugins.lockThe source, commit and approved hash of each installed plugin
$XDG_DATA_HOME/tuios/plugins/<id>/<commit>-<nonce>/One build of a plugin. It does not move after the build
$XDG_STATE_HOME/tuios/plugins/<id>/The plugin's state folder, with build.log
$XDG_CONFIG_HOME/tuios/plugin-config/<id>/The plugin's config folder

How do I

  • Install a herdr plugin? Run tuios plugins install owner/repo from a terminal outside tuios.
  • Write my first plugin? Run tuios plugins new NAME, then tuios plugins dev NAME.
  • Run a plugin that says "waiting for approval"? Attach to tuios and answer the dialog, or run tuios plugins approve ID.
  • Get the same plugins on a second machine? Copy plugins.lock with your config, then run tuios plugins install.
  • Move a plugin to a new version? Run tuios plugins update ID. To follow another ref, run tuios plugins install owner/repo@v0.4.
  • Remove a plugin? Run tuios plugins uninstall ID.
  • Stop a plugin from typing into my panes? Give it a tuios-plugin.toml with grants = ["read"], then install it again.
  • See why a plugin did nothing? Run tuios plugins list, then tuios plugins log ID and tuios plugins info ID.
  • See what a plugin costs? Run tuios plugins stats.

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page