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.

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 grantsA 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-CMade the plugin you.weather in weather.
Try it: tuios plugins dev weatherThe folder holds four files:
| File | What it holds |
|---|---|
tuios-plugin.toml | The manifest. It asks for the ui grant and names one action, Say hello |
hello.sh | The script that the action runs. It shows a notification |
README.md | How to try, check and install the plugin |
.github/workflows/plugin.yml | A 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 ROWScomes once, before the first frame. The maximum is 400 by 200.fps Nsets the time of each frame after it, from 1 to 50. The default is 10.color LETTER COLOURgives a letter a colour:#rrggbb, or an ANSI name fromblacktobright_white. An ANSI name follows the theme.framestarts a frame of ROWS lines.frame MSshows that frame for MS milliseconds.colorsafter 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 updateRun 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 placeThe 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.| Flag | Does |
|---|---|
-y, --yes | Install without the question |
--ref REF | The branch, tag or full commit. The same as SOURCE@REF |
--subdir DIR | The plugin folder in a repository given by URL |
--no-enable | Install and build, but leave the plugin off |
--no-build | Do not run the build commands |
--replace | Replace an installed plugin with the same id from another source |
--grant admin | Give 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:
| Name | What it does |
|---|---|
ovnfs | Opens copy-on-write checkouts of a folder with ovnfs, and diffs and applies them back. See ovnfs checkouts |
pr-status | Shows the pull request and CI state of the focused pane's folder in the dock |
sketch | Draws every Mermaid diagram type in tuios mermaid and in TML panels. tuios draws eight types itself |
themes | Adds 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 ovnfsIn the command palette:
| Entry | What it does |
|---|---|
| ovnfs: New checkout here | Opens a checkout of the focused pane's folder, and a pane with your shell in it |
| ovnfs: Checkouts | Lists 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: Diff | Shows what the checkout changed |
| ovnfs: Apply | Shows a dry run, then merges the changes into the folder when you type yes |
| ovnfs: Apply to a branch | Makes a branch in the folder's repository from the checkout's commits |
| ovnfs: Attach to a host | Makes 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 SNAPopens the work again. Removing a checkout from the list keeps its snapshots too. tuios shipleaves the remotes of an ovnfs checkout out of where it pushes.- The plugin holds the
uigrant. 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 commitThis 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.
--checkshows 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.
IDcan also be the source you installed from, such asowner/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, usetuios 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.lockon another machine, - from
tuios plugins link DIR, thentuios 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 PanesWhen 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.

- To allow the plugin, type
allowin the field and press Enter. For a plugin that asks foradmin, typeadmin. No single key or click allows a plugin. - Deny keeps the plugin off.
tuios plugins listthen showsdenied. 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-keyssends 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 panesA 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 tuiosA 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.
- The folders that
[plugins] dirsnames.tuios plugins linkadds one. - The tuios plugins folder,
$XDG_CONFIG_HOME/tuios/plugins/. - The plugins in
plugins.lock.plugins listshows them asmanaged. - herdr's registry,
~/.config/herdr/plugins.json. - 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
| Entry | When it runs |
|---|---|
| Build | Only at tuios plugins install, tuios plugins update or tuios plugins build ID. tuios shows each command first |
| Startup | When the daemon starts, and when you enable the plugin |
| Action | From the command palette, a command key, or tuios plugins run ID ACTION |
| Pane | From the command palette, or tuios plugins open ID PANE |
| Event | Each 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"]| Key | Required | What it holds |
|---|---|---|
api | yes | The plugin API version. Write 1. schema = 1 still works, and tuios plugins check warns |
id | yes | Letters, digits, ., - and _. Use yourname.plugin |
name | yes | The name people see |
version | yes | The version of the plugin, such as 0.1.0 |
description | no | One sentence |
min_tuios | no | The oldest tuios that runs this plugin |
platforms | no | linux, macos, windows. Leave it out for every platform |
[permissions] grants | no | The grants the plugin asks for. Leave it out for none |
[[build]] command | no | A command that install runs in the plugin folder |
[[process]] | no | A program that tuios runs. See below |
[[theme]] file | no | A theme file in the plugin folder. See Themes in a plugin |
[[saver]] | no | id and file, a frames file in the plugin folder. See A screen saver in a plugin |
[[cell]] | no | A dock cell. See Showing something |
[herdr] manifest | no | Take 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:
run | When it runs | Other keys | Cost when idle |
|---|---|---|---|
action | When you run it from the palette, a key or tuios plugins run | title, description, contexts | None |
pane | When you open it from the palette or tuios plugins open | title, description, placement, width, height | None |
event Unreleased | Each time an event in on happens. The command runs and exits | on | None. One run each time the event happens |
startup | Once, when the daemon starts or you enable the plugin | A 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.

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"]| Kind | Events |
|---|---|
pane | pane.created, pane.closed, pane.focused, pane.moved, pane.exited, pane.agent_detected, pane.agent_status_changed |
tab | tab.created, tab.closed, tab.renamed, tab.moved, tab.focused |
workspace | workspace.created, workspace.updated, workspace.closed, workspace.renamed, workspace.moved, workspace.reordered, workspace.focused |
worktree | worktree.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:
| Variable | Value |
|---|---|
TUIOS_BIN | The tuios binary that runs the plugin. Use it instead of tuios, which depends on PATH |
TUIOS_SOCKET | The socket of that daemon. The command line reads it |
TUIOS_PLUGIN_ROOT | The plugin folder |
TUIOS_PLUGIN_CONFIG_DIR | A folder for the plugin's settings. An update keeps it |
TUIOS_PLUGIN_STATE_DIR | A folder for the plugin's data. An update keeps it |
TUIOS_PLUGIN_ENTRY | The id of the [[process]], for an action or a pane |
TUIOS_PLUGIN_EVENT | The event that ran an event process, such as pane.focused |
TUIOS_PLUGIN_EVENT_JSON | The event as JSON |
TUIOS_PLUGIN_SESSION | The session of the focused pane. -s takes it |
TUIOS_PLUGIN_PANE | The focused pane. -w takes it |
TUIOS_PLUGIN_CWD | The folder of the focused pane |
TUIOS_PLUGIN_CONTEXT_JSON | All of the context above as JSON, with the agent and the selected text |
TUIOS_PLUGIN_ID, TUIOS_PLUGIN_TOKEN | Who 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 rightSet 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--actionnames 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,warningorerror. - The cells go when the plugin stops. A new daemon starts with no cells. Set them again from a
startupprocess or the next action. - To place a cell yourself, add
plugin/ID/CELLto 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.
| Grant | Lets the plugin |
|---|---|
| none | Do what every pane may do. A plugin that only opens a pane needs no grant |
read | List sessions and panes, read a pane's screen, and follow events in every session |
write | Type into your panes and shells, so it can run commands as you. It stops at an agent's approval prompt |
fan | Start agents with fan and start-agent |
ui | Show dock cells, panels and notifications. It cannot type into or read a pane |
admin | Everything else. It implies read, write and fan, never respond. It needs your approval on this machine |
respond | Refused. 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, notwrite.
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 admintuios 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
adminapproval does not cover files that the named files load, such as a sourcedlib.sh, a Python module ornode_modules. It does not cover an argument that is not a plain file name, such assh -c "./probe.sh"orgo run .. It does not cover programs on yourPATH, 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
setsidleaves the plugin. So does a command run overssh, or a process that pointsXDG_RUNTIME_DIRsomewhere 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 = 1stays. A plugin written forapi = 1keeps working in every later tuios that readsapi = 1. The manifest keys, theTUIOS_*variables, thetuios pluginscommands and the JSON verbs keep their meaning.- New things are additions. A tuios can add a key, a grant, a
runvalue or a variable inapi = 1. It does not change what an old one means. A plugin that uses a new one setsmin_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 infoshows a warning. Only a newapinumber 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 listis for people. Use--jsonin 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
| Path | Holds |
|---|---|
$XDG_CONFIG_HOME/tuios/plugins.lock | The 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/repofrom a terminal outside tuios. - Write my first plugin? Run
tuios plugins new NAME, thentuios 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.lockwith your config, then runtuios plugins install. - Move a plugin to a new version? Run
tuios plugins update ID. To follow another ref, runtuios 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.tomlwithgrants = ["read"], then install it again. - See why a plugin did nothing? Run
tuios plugins list, thentuios plugins log IDandtuios plugins info ID. - See what a plugin costs? Run
tuios plugins stats.
Related
Control Protocol
Drive a TUIOS daemon from scripts and programs with line-delimited JSON on its socket.
herdr Compatibility
Use tools built for herdr, such as Collie and herdr plugins, with TUIOS through herdr's socket API.
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.


