Skip to content

Plugins

New in v2.6.0. A plugin adds something to Whittl without touching Whittl's own code. It is a folder: a manifest.json that says what the plugin adds, and the Python files the manifest names. Sharing a plugin is zipping that folder. There is no registry, no account and no server.

Hello, world

The smallest plugin puts one line of text in Whittl's status bar. Make a folder called hello_world with two files in it.

manifest.json:

{
  "name": "hello_world",
  "api_version": 1,
  "version": "1.0.0",
  "description": "Says hello in Whittl's status bar.",
  "permissions": [],
  "contributions": [
    {
      "type": "panel",
      "entry": "plugin.py",
      "title": "Hello",
      "placement": "statusbar"
    }
  ]
}

plugin.py:

from PySide6.QtWidgets import QLabel


def create_panel(context):
    return QLabel("Hello from my first plugin")

Open Edit > Plugins > Manage Plugins..., press Open folder, and put the hello_world folder there. Press Refresh, tick Enable plugins, then tick hello_world. The line appears at the right of the status bar:

The bottom right corner of the Whittl window. The status bar reads "Hello from my first plugin" beside the context gauge.

That is the shape of every plugin. The manifest lists what the plugin contributes; for a panel, Whittl calls create_panel(context) and puts the widget it returns where placement says. context is the plugin's only way into Whittl: the theme's colours, the project's files, the usage log, the terminal, and so on, all listed on the plugin API page.

You do not have to write one by hand. File > New Project, pick Plugin, describe what you want, and Whittl writes it, checks it and installs it for you. Your first plugin walks through it.

What a plugin can add

Contribution What it is Where it runs
tool A function the AI can call while it works, offered beside Whittl's own tools Its own process
panel A widget in a tab beside Code, a readout in the status bar, or a dialog opened from Edit > Plugins Inside Whittl
menu_action An item under Edit > Plugins Inside Whittl
hook Code that runs when a generation starts or ends, a project opens, or you run the app; the one at the start of a generation may add guidance to the prompt Inside Whittl, on a helper thread
skill A skill file that joins the library while the plugin is on Read by Whittl

One plugin may contribute several of these. Whittl's own Assets, Archives, Terminal and Help tabs and the context gauge are plugins built exactly this way, which is the best evidence the system holds up.

The manifest format is on Plugin format; every field and value Whittl accepts is on the plugin API page, which is generated from Whittl's own code so it cannot drift.

Turning one on

Plugins are off out of the box, and two switches have to be on:

  1. Edit > Plugins > Manage Plugins..., tick Enable plugins. This is the master switch.
  2. Tick the plugin itself.

Dropping a folder in makes a plugin visible, never active. Nothing a plugin contains runs until you have looked at it and ticked it. The plugins that make up Whittl's own tabs are the exception: they are part of Whittl and are always on.

The first time the AI calls a plugin's tool in a session, Whittl asks you in the chat. Allow lasts for the rest of the session.

Plugins that ship with Whittl

Plugin What it adds
Assets, Archives, Terminal, Help Whittl's own tabs Always on
context_gauge The context gauge in the status bar (see Monitoring spend) Always on
token_usage_panel The Usage tab: what you have spent per day over 7, 30 or 90 days, split by model Off until you turn it on
search_project A tool the AI can call to search the project's files with a regular expression, with context lines Off until you turn it on

The last two are also worked examples: a panel and a tool you can open with Edit as project and read.

Where plugins live

Folder What it is
.whittl/plugins/ in your home folder Yours. An update never touches it. Open folder takes you there.
bundled_plugins/ in Whittl's install folder The ones that ship with Whittl. Replaced on every update.

A plugin in your folder with the same name as a shipped one takes its place. That is how you change a shipped plugin: select it and press Edit as project, which copies it into a project where you can change it like any other; your copy wins, and the original is left alone.

Whittl checks a plugin before it runs it

  • A tool's examples are run. A manifest can carry sample inputs with the output they should give. With Hold back plugins that fail their own examples ticked (the default), a tool whose examples fail is not offered to the AI until they pass. Run examples runs them on demand. Turn the box off while you are writing a plugin and failing examples are normal for a while.
  • A panel is built first in a separate, invisible copy of Qt. If it fails to build or crashes, it is not put in the window, and neither is anything else from that plugin: its hooks and menu actions would run the same code inside Whittl. A widget that comes out with no size is reported, because a status bar readout or a drawn widget with no height is invisible.
  • A hook is watched. A hook that raises an error three times, or keeps the window waiting more than 3 seconds, is switched off for the rest of the session. Whittl carries on without it, and the Plugins dialog marks the plugin "a hook is off" and says why on the hook's line.

Permissions are a disclosure, not a sandbox

A manifest lists what its plugin says it does (files, network, hardware, subprocess), and Whittl shows that list when you enable the plugin and when the AI first calls it.

Whittl does not enforce that list. A tool runs in its own process, so it cannot freeze or crash Whittl, but it runs with your access: it can read and write your files and reach the network whatever its manifest says. A panel, a menu action or a hook runs inside Whittl with Whittl's own access. The invisible build check above protects Whittl from a panel that crashes; it is not a defence against a plugin written to do harm.

Read a plugin before you enable it, the way you would read a script before running it. A plugin from someone else is exactly as trustworthy as that person.

Licensing

A plugin you write is yours to share or sell under any license you choose (Section 4 of Whittl's End User License Agreement). The plugins that ship with Whittl and the project templates, plugin templates included, are licensed under the MIT No Attribution License, so you can start from them, change them and ship the result without keeping any notice. Plugins written by other people belong to them, and Whittl does not review them.

Removing a plugin

Select it in Manage Plugins... and press Remove. That deletes it from your plugins folder; a plugin that ships with Whittl cannot be removed, only switched off. Deleting a project that installed plugins offers to remove them too, so a plugin does not stay behind running a deleted project's last code.

Next