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: Write a provider explains declarative packs, profiles with credential refresh, and provider definitions for a CLI, an ACP agent or a remote service. 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. A provider author also imports code from @timon-ai/sdk/provider and tests it with @timon-ai/sdk/testing (Write a provider). 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 14. API 3 added business events, workflows, transports and connections; API 4 added live updates from the host half to the browser half; API 6 lets a provider's discoverModels report thinking levels per model (providers) and adds AnchoredPopover to the UI kit. API 7 lets a provider plugin drive an agent with no local process (a remote dialect). API 11 gives provider authors the SDK's conformance bench, and a plugin declaring it has its dialect checked at registration. API 12 adds ctx.provider: the runtime a provider is written with, supplied by Timon so that a fix reaches every plugin, the services that need a privilege only Timon holds, and registration of a whole ProviderDefinition. API 13 lets a plugin add a control or a drawer to the built-in browser (useBrowserChrome, browser:control) and replace the model selector through the model.picker slot (cookbook). API 14 adds kind: dictation: a speech-to-text engine in the dictation.engine slot, with its dictation manifest block and the sensitive dictation:engine permission. The calls added by contracts 8 to 10 are on the page of the feature they belong to, with their permissions in Permissions. 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. Before sending a plugin to anyone else, read Ship to someone else: no absolute path or personal data, everything in the package, and the check to run first.
The SDK API reference is generated from the public TypeScript entry points: @timon-ai/sdk, @timon-ai/sdk/provider and @timon-ai/sdk/testing. Implementation comments and private source links are deliberately excluded; use these guides for behavioural explanations.