Documentation / Plugin System

Plugin System

Aphotic base is the shell, rice/theming, Settings, and core Quickshell modules — everything else, AI capabilities included, is an independently installable and removable plugin. This page covers the manifest format, what each capability actually does, and the current plugin roster. For the day-to-day commands, see CLI Reference’s Plugins section.

The manifest (plugin.toml)

A plugin is a directory with a plugin.toml manifest declaring what it is and what it touches. Manifest versions are additive — a v1 plugin (just [plugin] + a theme hook) parses and behaves identically under v2 or v3, nothing needed a migration.

[plugin]
name = "example"
display_name = "Example Plugin"
description = "..."
version = "1.0.0"
author = "..."
category = "ai"                    # dev | security | mobile | ai | theming | productivity
capabilities = ["theme-hook"]      # see Capabilities below -- a plugin can declare more than one

[requires]
binaries = ["some-binary"]         # checked before enabling; warns and no-ops, never blocks

[hooks]
on_theme_change = "hooks/on_theme_change.sh"

[owns]
config_keys = ["someSettingKey"]           # Settings.qml keys this plugin is the sole consumer of
external_config = ["~/.some/foreign.conf"] # a foreign program's config file this plugin touches

[ui.dashboard_tab]
id = "example"
icon = "extension"
label = "Example"
component = "qml/ExampleTab.qml"

[harness]
wire = "hooks/wire.sh"     # see the harness-hook capability below
unwire = "hooks/unwire.sh"

ui-surface covers eight distinct surface kinds, one [ui.*] block each (a plugin can declare more than one):

requires_layer/requires_data are both optional on every kind above. Omit both and the surface is available on every install — PluginRegistry treats an empty gate as “no gate,” not as “gated on nothing being true.”

category drives filtering in aphotic plugin list --remote and Settings → Plugins. Security-category plugins live in a separate index that stays untrusted (and unfetched) until aphotic plugin trust-security-index is run once — the same “opt into the riskier stuff explicitly” pattern as the exploit layer’s BlackArch confirmation.

Capabilities

A plugin declares one or more capability tags in [plugin].capabilities. Each unlocks a different mechanism. Aphotic 2.0.7 hosts ui-surface, theme-hook, project-hook, workspace-hook, harness-hook, profile, cli, chat-provider and action, and the surface kinds dashboard, notch, settings, workspace, overlay, fullscreen-overlay, background and pet_action. A plugin declaring something this build doesn’t host is checked at install: if nothing it declares is hosted, aphotic plugin install refuses it (“needs a newer Aphotic”); if only part is, it installs with a warning that the rest stays dark until you update, and aphotic plugin list keeps flagging it as partially hosted.

The shell runtime API ([api])

Surfaces and hooks say where a plugin mounts; [api] says what it may ask the running shell for once it’s there:

[api]
version = 1
uses = ["context.observe", "resource.observe"]

The shell hands each plugin a handle carrying only the calls uses names, checked again at call time, so disabling or removing the plugin revokes it. This build speaks API version 1, with context.observe, context.request, resource.observe, surface.declare and notifications.publish; context.request is rate-limited per plugin. A plugin written against a newer API version is refused at install. aphotic plugin api [--json] prints what the running build speaks.

[owns] is informational, not an auto-revert list: config_keys/external_config show up in aphotic plugin list --json and Settings → Plugins so a plugin’s footprint stays auditable, but removing a plugin doesn’t reset those keys to their built-in defaults — a stale agentGraphQuality value, for instance, causes no dead UI or drift on its own, and a reinstall just picks the same value back up. Files and UI surfaces do get removed symmetrically on aphotic plugin remove — that part is a hard guarantee, not just a convention.

Current plugin roster

All distributed from the separate aphotic-plugins repo — aphotic plugin install <name> clones it locally the first time, then just copies the one plugin out of it.

18 plugins as of this writing, aphotic plugin list --remote is always the current count:

Installing all three harness-hook plugins for the harnesses you actually use, plus agent-graph/agent-audit/agent-notch-tile, reproduces the exact live-tracking behavior that used to be bundled automatically into the ai layer before the plugin architecture landed (v2.0.0) — see Agentic Workflows’s “Turning it on” section for the one-time setup.

Four UI plugins above — Desktop Pet, Spectrum, Live Wallpapers and Deep Signal Screensaver — are deliberately ungated: their surfaces declare no requires_layer and no requires_data, so they’re relevant to every install regardless of profile or layers. (theming is a category, not a layer: the four gateable layers are ai, dev, gaming and security, where security means any exploit/exploit-* layer, so a theming plugin has nothing to gate on and being installed is the opt-in.)

CLI

aphotic plugin list [--remote] [--refresh] [--json] [--category <name>]   # installed, or browse the (cached) remote index
aphotic plugin install <name> [--link]                        # clone (or symlink, for local dev) a plugin
aphotic plugin update <name>                                  # refresh a plugin's files from the repo
aphotic plugin enable|disable <name>
aphotic plugin remove <name>
aphotic plugin trust-security-index / untrust-security-index  # opt into (or back out of) the security-category index
aphotic plugin validate <dir>                                  # check a plugin folder before installing it
aphotic plugin api [--json]                                    # the runtime API version and calls this build offers

aphotic plugin list flags installed files that have drifted from the registry — if the on-disk version of a plugin doesn’t match what plugins.json records, it shows a drift indicator so you know an update is available.

Settings → Plugins covers the same ground with a GUI: an Installed list (enable/disable/remove, missing-dependency warnings, capability chips, a “Wires: …”/”Uses settings: …” disclosure for [owns]) and a Browse available list pulled live from the registry’s index, filterable by category.

See also

• Build a Plugin — a worked tutorial: manifest, component, validate, test, publish
• Agentic Workflows — the flagship ui-surface plugins (Agent Graph, Agent Audit, Agent Notch Tile) and the three harness-hook plugins they pair with
• Supported Features — where the plugin system fits among everything else
• CLI Reference — full command syntax

View public Wiki source ↗