Plugins

Use plugins for tools such as Markdown and image viewers or AI agent integrations. Explore the bundled plugins, add new ones, and manage which tools run and what permissions they have.

What a plugin is

Features such as the Markdown viewer, the image viewer and the Claude Code integration are provided not by the Tasty core but by plugins. A plugin runs as a separate process, declares what it adds (Surface kinds · tool menu items · tasty subcommands · settings pages · file handlers) and which permissions it needs, and Tasty accepts its requests only within the granted permissions.

• Plugins are installed in ~/.tasty/plugins/<id>/, with logs in ~/.tasty/plugins-logs/<id>.log.
• The bundled plugins are installed automatically on first launch. After that they can be disabled or removed exactly like plugins you installed yourself. A bundled plugin you removed is not reinstalled on the next launch.
• When a plugin is disabled, the Surface kinds · commands · menu items it added disappear with it. This takes effect right away when you disable or remove it while Tasty is running: opening a new Surface of such a kind fails with the reason that the plugin providing it is turned off or has not reconnected yet. Surfaces you already opened stay as they are and pick up again when you enable the plugin, but their scroll position and any unsaved content are lost.

When you enable or disable a plugin or change its permissions, Tasty confirms the save before applying the runtime change. Installation and trust choices also report their result after saving. A failed or unconfirmed save is not reported as success. An enable saved during shutdown takes effect on the next launch; shutdown does not start a new plugin process. A change whose result remains unconfirmed at the shutdown deadline is not reported as successful or automatically replayed.

Bundled plugins

How to use each Surface kind is in Opening files. There are also demo · experimental plugins that ship only in development builds; they are not included in the distribution.

Settings added by plugins

In the Settings window, plugin pages appear in two places.

• Appearance > Markdown — Font settings applied only to Markdown Surfaces · Allow remote content (off by default — blocks external http/https resources the document loads).
• Appearance > HTML — Default zoom (%) · Color scheme (follow theme / light / dark) · Allow remote content (off by default — blocks external http/https resources) · Sandbox scripts (on by default).
• Plugins > Claude Code — Spawn child warning threshold and so on.
• Plugins > Codex — Spawn child warning threshold · Default approval policy · Default sandbox mode.

A plugin that adds a Surface drawn as a web page, even one you installed yourself, applies the zoom, color scheme, allow remote content, and sandbox scripts values from its own settings page to that Surface, the same way HTML does. Values you have not changed follow the defaults the plugin sets, and on a Surface that supports the zoom shortcuts, the shortcuts change that plugin’s zoom value.

The Configure button in the plugin window goes to these pages too.

In the light theme, the trusted verdict uses dark green text and a shield. It describes the signature verdict; it does not certify code review or runtime safety.

The plugin window

Press the Plugins button at the very bottom of the sidebar. It has three tabs.

Installed

The Installed tab. Pick one from the list on the left and the details appear on the right. Filter installed… above the list filters by name.

• The line under the name at the top of the details shows the authors and the plugin id. If the plugin has a homepage, it appears at the end of the same line. An http:// or https:// address is an underlined link that opens in your browser (if the browser can’t be started, a notice says it couldn’t be opened); any other value is shown as plain text.
• Rows in the list are marked Disabled or Running. If a plugin is enabled but fails to run, a red marker appears with the notice Failed to connect. Check the plugin’s configuration in Settings.
• Permissions — The list of permissions this plugin has been granted. Read-only here; it cannot be changed.
• Commands — Keybinding commands added by the plugin, one command and its shortcut per line. On macOS the shortcut shows the keys you actually press, in the order Ctrl · Option · Shift · Command, and Option, Shift and Command follow the modifier display style (word or symbol) under Settings > General. Change the keys under Settings > Keybindings > Plugins.
• Install path · Log — The last section of the details. A long path wraps so it is shown in full, and you can drag to select and copy it. Open folder on the right of the heading row opens the install folder in your file manager. If the file manager can’t be started, the plugin window shows a notice that the folder couldn’t be opened.
• The bar under the details stays visible while you scroll the details.
  • The switch on the left — The label next to it shows Enabled / Disabled. Clicking the label also toggles it. Turning it off cleans up the process; turning it on starts it again.
  • Configure — Goes to the plugin’s page in the settings window.
  • Uninstall — The bar turns into a confirmation in place, with Cancel and Uninstall buttons. Pressing Uninstall deletes the install folder; the plugin’s settings stay until you delete them. For a built-in plugin, the note says it won’t be installed again on the next launch. When the confirmation appears, keyboard focus is on Cancel, so Enter cancels right away; Esc also cancels, even after you switch to another tab. Selecting another plugin cancels the confirmation and brings back the normal bar.

Attention

The Attention tab. Plugins whose registration was rejected or that failed to run are collected here with the reason. As for installed plugins, the top of the details shows the name, authors and id, plus the homepage link when it is an http:// or https:// address, with the description below. For a plugin whose signature is invalid, the manifest can’t be trusted, so its description and homepage are not shown; Description hidden — the signature is invalid. appears in place of the description.

Add plugin

The Add plugin tab.

1. In the Plugin folder field, enter a folder containing tasty-plugin.toml, or pick one with Find folder…. The Tasty folder picker confirms the selected subfolder, or the current folder when no row is selected. Double-click enters a folder; Enter confirms it. Cancelling keeps the field unchanged.
2. Choosing a folder validates it immediately. If you typed a path, press Verify. The manifest card appears right under the field: name · version · id · authors · description · required permissions · surface kinds · source path, plus the homepage when the plugin has one. An http:// or https:// address is an underlined link that opens in your browser (if the browser can’t be started, a notice says it couldn’t be opened); any other value is shown as plain text. With several authors, the first one is followed by +N; hover to see them all. Editing the path clears the card, so press Verify again. If the folder has no tasty-plugin.toml or the file can’t be parsed, a Can’t read tasty-plugin.toml box takes the card’s place with the reader’s error on the line below. If the file reads but breaks a manifest rule (for example, the listed binary is not in the folder), a tasty-plugin.toml is not valid box appears in the same place with what is wrong on the line below. Fix the path and press Verify again.
3. The box under the card tells you how the signature was judged: Signed by a trusted publisher, Permissions changed, or Unverified plugin. For an unverified plugin the box gives the cause (a key not in the trust list, a missing public key file, no signature, or a failed signature check) and warns that the plugin runs with your account’s access and that its permissions only limit what it can ask Tasty to do. When the judgment involves a key, the box shows the fingerprint, which you can copy with its button. A long fingerprint shows only its first and last 8 bytes with … in between; hovering or copying gives the full value.
4. The left of the bottom bar shows how many permissions the plugin will get. Press Add plugin. For changed permissions the same button reads Trust & add; pressing it records the new permission set in the trust list. Permissions only limit what the plugin can ask Tasty to do; they don’t isolate the plugin program from your files, network or other programs. For an unverified plugin the button reads Add anyway (Trust key & add anyway for a key not in the trust list), and Cancel has focus at first, so Enter or Esc goes back without installing. Press it only if you trust where the plugin came from. The choice is remembered until the manifest changes or the plugin is removed; once installed, the plugin has no other restriction beyond its mark in the list. While adding, the button reads Adding….
5. If the plugin is already installed, the button stays disabled and Already installed is shown on its left.

Installing grants the permissions the plugin requests. Review the permission list in the preview before adding it.

Permissions

A plugin declares the permissions it needs in advance. Tasty rejects requests to the host when the required permission has not been granted. Permissions only limit the requests a plugin sends to Tasty; they do not stop the plugin process from reading and writing files or connecting to the network on its own. Install only plugins you trust. Common names and their meanings:

Permissions granted to the bundled plugins:

Removing or restoring individual permissions is done only from the CLI (below).

The tasty plugin command

Use it from a terminal while Tasty is running. The output is JSON.

install checks the signature before copying the folder. For an unverified plugin it warns about the cause and the risk, installs nothing, and shows the tasty plugin install --allow-unverified <folder> command to use if you trust the source. When the signature check refuses the install, it tells you the actual reason (no signature, a key you have not trusted, a public key file that is missing or does not match, and so on) and leaves nothing behind in the plugins folder, the permissions or the trust list. Fix the problem and run the same command again to install. If the plugin is registered but then fails to start, the installed folder stays; check tasty plugin logs <id> for the cause.

When a plugin does not start, a warning is left in the notification list. If it fails several times in a short time and Tasty turns it off automatically, a separate error notification is left and the plugin is not started until you turn it on again. Repeated failures of the same plugin that you did not turn on again are grouped into one. Each time you turn it on yourself, that result gets its own notification. The notification body and tasty plugin logs <id> show the cause.

enable and disable require an installed plugin ID. An ID that is not installed returns an error and leaves settings unchanged. Use tasty plugin list to find installed IDs.

disable starts shutdown, normally in the background. If the plugin has not exited after a 2-second grace period, Tasty attempts to force-stop it. Those 2 seconds are not a limit on the entire operation; waiting for the OS to finish the process can take longer. An enable during shutdown waits for the previous process to finish before starting a new one. tasty plugin enable then waits (up to 15 seconds) for the new plugin to connect and reports the result. Pass --no-wait to return right away. In that case, and when an agent calls IPC directly, the reply only says the start was accepted, so check the result with tasty plugin show <id>. If startup or connection fails, check the notification and the logs.

While closing a Surface of a stuck plugin takes time, other commands and input are still handled as usual. If you disable that plugin while the close is waiting, the close succeeds as soon as the process exits. If you quit Tasty in the meantime, quitting waits for that close to finish (up to 5 seconds).

tasty plugin list
tasty plugin permissions com.tasty.git-viewer
tasty plugin disable com.tasty.clipboard-viewer
tasty plugin logs com.tasty.markdown --follow

Example output of tasty plugin permissions com.tasty.git-viewer:

{
  "granted": ["ui.tool_item", "fs.read", "ui.popup"],
  "id": "com.tasty.git-viewer",
  "manifest": ["ui.popup", "ui.tool_item", "fs.read"]
}

Troubleshooting

Keep exploring

• Opening files — How to use the Markdown · image · HTML Surfaces.
• Working with Claude · Codex — The Claude Code · Codex plugins.
• Settings — Where the plugin settings pages are.