Wuu plugins

Manage standalone MCP services in the Plugins catalog. MCP services supplied by a plugin appear on its detail page, with their connection and login controls.

A Wuu plugin packages agent behavior, desktop UI, or other extension contributions. A package can include tools, skills, hooks, MCP servers, themes, and settings. Enable only code you trust: plugins run with your user authority and are not sandboxed by Wuu.

Install a local package

Open Skills & Plugins and install a local directory or zip package. Installing confirms trust in that source and enables the plugin. There is no central marketplace, and the installer does not fetch npm packages or Git repositories directly.

The CLI uses the same trust rule:

wuu plugin install ./my-plugin
wuu plugin list

Use the ID declared by the package. Installation copies files under plugins/ in Wuu’s home directory, normally ~/.wuu/plugins/; WUU_HOME changes that location. Installation records the source and the exact package fingerprint in the selected configuration service. Activation still checks compatibility and dependencies; inspect diagnostics if the plugin cannot start.

Update, disable, and remove

Install a replacement package from its directory or zip, or use:

wuu plugin update my-plugin ./my-plugin

Updates from the same recorded source retain trust and the enabled or disabled choice. A different source, or an older grant without a recorded source, leaves the update pending and the installed generation active. Confirm that source change in the detail page or with wuu plugin approve my-plugin. A changed version or content fingerprint alone does not require another approval. Copying files directly into the installed directory is not the update workflow.

For local packages, the source is the canonical directory or zip path, including symlink resolution. Replacing a zip at that same path is a same-source update; moving to a different path requires confirmation.

A committed disable stops the plugin across retained runtime generations without removing its files: native executions are canceled, owned MCP servers cannot reconnect, and future legacy hooks and transforms are removed. Already-running legacy hooks retain their caller lifetime; completed effects and conversation history remain. This differs from a same-ID update, which lets active work finish on its original generation. Remove the package when it is no longer needed:

wuu plugin disable my-plugin
wuu plugin enable my-plugin
wuu plugin remove my-plugin

Settings and plugin storage are preserved by default. Removal does not erase all data the plugin created or undo completed operations.

Recovery and troubleshooting

An optional add-on that fails initialization, preparation, or activation does not block CLI disable/remove operations in the default composition. Failed runtimes remain unavailable and appear in wuu plugin describe diagnostics. wuu plugin list --json lists discovered packages without starting their runtimes; it is not a live activation-status report. Explicit composition modules and selected service bindings remain required, and invalid configuration is never replaced with defaults to perform a recovery write.

If an operation reports that the change was committed but runtime activation failed, the settings or package change has already taken effect. Read the new inventory’s failure diagnostics before retrying; the old runtime is not automatically restored. See the generation lifecycle.

Catalog entries keep their name and description: + enables a plugin, and … manages an enabled plugin. A family uses … when any component is enabled; otherwise + opens its component page. Component counts appear on that page. Permission and update decisions remain in plugin details. Runtime failures and dependency diagnostics use shared toast notifications without changing the catalog layout; failed plugins retain a Retry action in their details.

If desktop code fails to render, Wuu isolates the failing contribution where possible and keeps plugin management and default-UI recovery available. Disable the suspected plugin and retry with the default interface. The CLI is useful when the desktop contribution itself is broken. Safe mode provides a recovery path after plugin-related startup failure; it does not certify the package as safe to re-enable.

What plugins can provide

Agent runtimes can register tools, contribute context, observe supported lifecycle events, and provide or consume versioned services. Desktop modules can add views, fixed insertion points, semantic rendering replacements, conversation cards, and styles. Declarative themes and settings do not require a desktop module; see themes and settings.

Bundled features use these mechanisms too. Guides cover subagents, automations, and memory. The Peers plugin lets an agent contact existing conversations in the same workspace; it is separate from creating a child subagent.

OpenDesign presets

The optional OpenDesign Presets plugin contributes one opendesign skill. Use it to choose a design system, start from an artifact template, or apply craft rules while building a website, dashboard, mobile interface, or HTML presentation. For example: “Use OpenDesign to make a Linear-inspired dashboard.” The skill searches its local catalog and reads selected resources on demand.

Install a built opendesign-presets directory or zip through Skills & Plugins or wuu plugin install. To build it from source, follow the package instructions. The package pins its upstream revision, preserves attribution and licenses, and works without an OpenDesign installation. Disable opendesign-presets to remove its skill from the available catalog.

This package provides presets and a Wuu workflow. OpenDesign’s canvas, element comments, direct editing, and media providers are separate application features. Media entries supply prompt recipes; generation still requires an available tool. Templates may reference optional libraries or remote assets. The skill adapts upstream preview and output conventions to the current project and Wuu tools.

Monitor background events

The bundled Monitor plugin runs a shell script while the agent continues working. Ask it, for example, to watch CI and report a failed check immediately, then finish when every check passes. Scripts should print relevant changes to stdout and diagnostics to stderr; each stdout batch can wake the conversation or steer its current turn. Monitor events are observations, so they do not answer a question that is waiting for you.

While watches remain active after a turn finishes, a mascot row below the latest turn shows what is still being monitored and disappears when they end. Monitor has no dedicated desktop panel. Ask the agent to inspect or stop a watch; monitor_tasks lists its status and reads retained output. Explicit stops tell the agent not to restart the watch unless asked. New event deliveries, including monitor completion, stay out of the chat transcript. The agent can report useful progress, results or failures; raw events remain in model history and retained monitor output.

monitor accepts command, description, optional timeout_ms (up to 10 hours, the default), and persistent. A persistent watch has no deadline and lasts until stopped, its conversation is archived/deleted, or its plugin runtime ends. Watches started in a private child conversation pass to its parent when the child finishes. monitor_tasks lists, reads or stops watches in the current conversation.

Standard output produces events; standard error is retained as diagnostics and included in failure or timeout reports. Read either stream with monitor_tasks using stream: "stdout" (default) or stream: "stderr", with independent byte cursors. Blank lines are ignored, incomplete lines flush on exit, and events are batched every 200 ms. Delivery allows a burst of 10 batches and replenishes one every two seconds. Excess batches are counted; 30 seconds of sustained overload stops the script. Event lines are shortened to 500 bytes and batches to 3,000 bytes, while tool reads use the retained process logs. Use line-buffered pipelines and handle transient network failures in scripts.

Shell execution uses the conversation’s captured local or remote environment and its shell permission and sandbox policy. Separate streams require host.process 1.2 and backend support; unsupported backends fail explicitly. Disabling the plugin or retiring its runtime stops its processes. On restart, running records become interrupted and retain their recent output; scripts are never automatically restarted. Up to 64 task records are retained.

Develop a plugin

Start with the agent quickstart or desktop quickstart. Local development is distinct from installing a distributable package. The authoring reference covers manifests, development commands, version requirements, and package relationships.

Wuu does not audit, certify, or host third-party extensions. Check compatibility with your Wuu build and review the security model before running unfamiliar code.