Overview
A Timon plugin is an ESM npm package with two independent, optional halves: host code executed by the daemon and a browser bundle loaded by the client. Host extensions use a restricted PluginContext; UI extensions register components in slots through ClientContext.
The same registration model supports widgets, pages, behaviours, themes and layouts. A bundle installs several separate plugin identities. Start with Your first plugin, then read the manifest, slots and permissions.
Providers are plugins too: Add a provider explains declarative packs, profiles with credential refresh, and custom CLI dialects. A compatible endpoint used only on your own installation needs no plugin; use Add a provider in Settings.
The public contract
Import TypeScript contracts from @timon-ai/sdk. The package in this source tree is currently private; no public npm availability is assumed. Obtain the SDK and example packages with your developer distribution.
apiVersion is the minimum contract a plugin requires. A daemon accepts versions up to its implemented contract and rejects a newer requirement. The current source exports contract 4. API 3 added business events, workflows, transports and connections; API 4 adds live updates from the host half to the browser half. ctx.can() supports optional capabilities after admission; it cannot make an unknown manifest permission valid on an older daemon.
PluginContext is an API façade, not a JavaScript sandbox. A host plugin runs in the daemon process with the OS account's privileges. Install only code you trust; permissions and signatures do not turn hostile Node code into isolated code.
Package identity
The npm package name and timon.id are separate. Use your own npm scope. The current manifest validator accepts IDs matching [a-z0-9-]{3,40}, such as acme-weather; it does not accept a scoped ID containing /. Bundled product IDs use their own catalogue convention. Use the manifest ID for configuration, plugin commands and bundle membership.
Always encode IDs used as URL segments with encodeURIComponent; do not make routing depend on the present character restrictions.
Continue with the example cookbook for verified source excerpts from all supplied packages.
The SDK API reference is generated from the public TypeScript entry point. Implementation comments and private source links are deliberately excluded; use these guides for behavioural explanations.