Plugin System
Understand installed and project-level Daintree plugins: installation, project trust, management, updates, and building your own repository tools.
Plugins extend Daintree with panels, commands, toolbar buttons, settings, recipes, skills, agents, and integrations. Installed plugins live in ~/.daintree/plugins/ and operate across projects. Project-level plugins live in the repository at .daintree/plugins/ and supply tools for that project alone.
Each machine keeps its own plugins. In a window on a remote host, the host's plugins are the ones that run: their code runs on the host next to the project, their views render in your window, and Daintree asks before a host plugin's view first runs on this computer. Settings → Hosts compares the two machines and installs a plugin on the host one at a time. See Plugins Across Machines.
A project plugin can turn a repository into a small application for its team: a release desk, content studio, data workbench, or operations console. Start with Project-level Plugins for use cases and the available surfaces, Building Project Plugins for the development workflow, Project Plugin Surfaces for a custom starting screen, and Project Plugin Trust & Management for running repository code.
Installing a plugin
A packaged plugin is a .dntr file: a standard ZIP archive with plugin.json at its root. There is no marketplace and no registry hosting plugin files; authors publish .dntr files on GitHub Releases, their own site, or an internal artifact host. Daintree's community catalog is a reviewed list that pins each listed release to its URL and SHA-256. Packaged Daintree distributions associate the .dntr extension with the app, so opening a downloaded archive can start the install flow.
| Path | How |
|---|---|
| Drag and drop | Drop one or more .dntr files anywhere on the Plugin Manager's body. A multi-file drop installs the files one after another with no preview or confirmation; cancelling stops the rest of the batch. |
| Install from file | Install plugin > Install from file in the Plugin Manager's header, or double-click a .dntr in your file manager. |
| Install from URL | Install plugin > Install from URL in the Plugin Manager's header. Paste a link to a .dntr. |
| Browse | Browse in the Plugin Manager's header lists the community catalog, and any catalogs in the same format you add under Settings > Plugins. A listing is reviewed for its source and bytes, not for safety, and is not a Daintree endorsement. |
| Sideload | Put an unpacked plugin directory at ~/.daintree/plugins/{publisher}.{name}/ and restart. This is the path for plugins you build yourself or share inside a team via a private repo. |
| Deep link | daintree://plugin/install?url=… opens Daintree and pre-fills the URL install dialog; adding &sha256=… previews and installs only an archive with that digest. daintree://plugin/install?id=publisher.name previews the catalog's newest stable release (a prerelease only when there is no stable one), or the release named by &version=, and installs it after you confirm. daintree://plugin/open?id=publisher.name opens the manager on that plugin. |
| CLI | daintree-plugin install <path-or-url> installs into the running app; --sha256 <hex> refuses any other archive and never replaces an installed plugin. daintree-plugin uninstall <pluginId> removes it. |
Archive installs validate and hash the package, check host compatibility, extract it into a temporary directory, and atomically replace the installed directory before loading. An archive opened from the operating system, a URL install (deep links included), and a catalog install show a preview with identity, capabilities, and contributed recipe names before anything is installed, and a URL or catalog install then installs only the archive that preview was read from. Drag-and-drop, Install from file, and the CLI install without that preview. Sideloaded directories and project plugins are discovered directly rather than passing through archive extraction.
Installing a validated archive directly over an existing plugin does not compare version order: there is no downgrade gate and no identical-version block. Two exceptions: a catalog update must be a newer version than the one installed, and an archive that switches the plugin between app-wide and per-project instanceMode is refused until you uninstall the old one. The swap keeps the original installedAt and records an updatedAt. When you confirm an update, Daintree installs exactly the archive the confirmation previewed; if the download no longer matches it, nothing is installed.
A plugin whose engines.daintree range does not include the running version still loads, with a one-time Plugin version mismatch warning. See Version compatibility.
URL installs have a 30 MiB cap, a 30-second deadline, archive content-type checks, and at most five redirects. The shared download guard requires HTTPS and rejects embedded credentials, private, loopback, and link-local targets. The UI still displays a warning for HTTP, but confirming it does not bypass the HTTPS guard.
.dntr archives are not signed, and Daintree performs no publisher-identity check at any install path. The SHA-256 hash proves that two fetches of the same URL returned the same bytes; it proves nothing about who produced them. Install only from sources you would trust with your shell.The Plugin Manager
The Plugin Manager is a full-screen view for browsing installed plugins, inspecting their settings and permissions, and managing lifecycle actions. Escape closes it.
Open it from Plugin Manager… in the app menu, from the command palette (Open plugin manager), from the plugin toolbar tray, or from Settings > Plugins. There is no default keyboard shortcut; bind one yourself from Keyboard Shortcuts if you open it often.
The header carries Browse, Install plugin (a menu with Install from file and Install from URL) and, when any URL- or catalog-installed plugin can be checked, Update all. Below it the layout is master/detail, led by the Search plugins field. The left column lists everything installed, grouped by catalog category: Forge providers, AI & agents, Workspace, and Other. A plugin's category comes from its manifest category field when it declares one, and is otherwise derived from what it contributes. A disabled plugin stays in its category, dimmed with its switch off, so toggling it in the unfiltered list never moves the row out from under your cursor. Under a filter such as @disabled, changing its state can drop it from the results.
Each row carries the plugin's icon, name, version, and tagline, a quiet source pill when the install source is not the default, and Dev for a plugin linked by the development loop. A row in trouble replaces its tagline with one status, the most urgent that applies: Blocked, Failed to load (with a one-click retry), Restart required, or Update available with the new version. A plain disabled plugin shows no status; its switch already says so. The enable switch sits at the right of the row as its own control. Repository plugins for the current project appear in their own This project section; see Project Plugin Trust & Management.
Search and filter operators
The search field does fuzzy matching on name and description, and also accepts VS Code-style @ operators that narrow the list before scoring. A row of chips below the field advertises the category filters and @disabled so the syntax is discoverable rather than hidden.
| Operator | Matches |
|---|---|
@builtin | Plugins that ship with Daintree. |
@installed | Plugins you installed yourself. |
@enabled / @disabled | Current enable state. |
@cat:<id> | Category: forge, ai, workspace, other. |
@cap:<id> | Plugins declaring a capability, e.g. @cap:shell:exec. |
An unrecognized @foo token is left in the free text rather than silently dropped, so a half-remembered operator still gets you a name match instead of an empty list.
The detail pane
Selecting a plugin fills the right pane with its identity, version, provenance, lifecycle actions, and a tab bar. Tabs are earned by content. Overview is always present; Settings appears only when the plugin declares settings fields, a settings view, connections, or a setup checklist (a per-project package keeps these in each project's instance instead), Permissions only when it declares capabilities or worktree delete notes, and MCP servers only when it contributes one. Logs appears once the plugin has logged something. Performance appears once the host has measurements; Styles is available for an enabled plugin with a non-PTY panel and matching view. See performance and styling checks. A minimal plugin gets one tab, not three with two of them empty.
With nothing selected, the pane shows the catalog home: a grid of installed plugin cards, grouped under category headings; a search turns it into one flat grid of matches. Browse replaces it with the community catalog's listings, each naming the catalog it comes from and marking plugins you already have. The catalog is fetched only when you browse, install, or check for updates; with background update checks on, that check can run shortly after startup.
While an install is running, a progress banner reports the phase it is in (Downloading the plugin, Unpacking the plugin, Checking the plugin, Finishing the install), names the archive entry being written, and offers a cancel. If a change cannot be reconciled in the running session, a bar across the header offers a restart behind a confirm dialog. That bar clears itself if the condition resolves while it is open.
Settings > Plugins still exists, but it is now a launcher: the installed count, a button that opens this view, the catalogs you have added, and an opt-in toggle for background update checks.
Managing installed plugins
Enable and disable, without a restart
The switch on each row is live. Disabling unloads the plugin in place: disposers run, its contributions leave the palette and toolbar, and any MCP subprocess it started is killed. Enabling re-forks the worker and loads it again. The Restart required badge reads true only in the brief window where the persisted desired state and the running state have not yet reconciled; it is a transient cue, not the normal path.
Settings
A plugin that declares a settings schema gets a generated form. Settings can be user-scoped, project-scoped in the repository, or local to this machine and project. Local scope is useful for an interpreter path or per-project credential that should not travel with Git. A secret setting is encrypted through the OS keychain, and kept out of the repository even at project scope. Where no keychain exists, such as on a headless Linux host, the form says so and the secret is not saved.
Updates
Nothing auto-updates. Select a plugin and click the refresh button in its detail pane: Daintree re-fetches the URL it was installed from and compares the SHA-256 of the archive against the installed one, so a new build is detected by content change regardless of what its version string says. A catalog install is checked against a freshly fetched catalog instead, and is offered only a newer reviewed release; if the catalog no longer lists it, the check says it was delisted and the installed copy keeps running. Update all checks every URL- and catalog-installed plugin and then drains the ones with a change through the same per-plugin confirm: it never installs anything silently. Sideloaded and file-installed plugins have no origin to re-fetch, so they are updated by reinstalling.
Uninstall
Uninstall runs a full cascade: unload the plugin and run its disposers, terminate any MCP subprocesses it spawned, revoke every stored consent pin so a later reinstall re-prompts rather than inheriting prior approvals, and delete its directory. Settings, secrets, connected accounts, and stored data are kept by default so an API token or sign-in survives a reinstall; tick Also delete its settings, connected accounts, and stored data (or pass --delete-settings to the CLI) to delete the settings, secrets, account sign-ins, and user-scope storage this machine holds for it, across every project. Databases and other files the plugin created are kept either way, and so is anything under a repository's .daintree/, including project settings and project or worktree storage: removing those is the project's business. When a plugin with saved cloud accounts is uninstalled from the manager, it also asks whether to keep those accounts, with their credentials sealed for a reinstall, or remove them and their hosts; the CLI keeps them. Either way, no machine is stopped or deleted at the provider.
The blocklist
Daintree keeps a small remote blocklist and refuses to load anything it names. The list is cached on disk for offline enforcement and refreshed when the cache passes six hours. Startup enforces the cached list at once and refreshes it in the background, unloading anything a newer list blocks; only a first start with no cache waits for the download, for at most 8 s. A fetch failure does not invent new blocks; any cached blocklist remains enforced. Without a usable cached list, the fetch fails open. A blocked plugin still appears in the manager, dimmed, with a Blocked badge, a stated reason, and its switch disabled: the refusal is host policy, not something you toggled.
Project visibility
Project settings → Plugins controls which installed-plugin UI appears in that project. Show here hides or reveals panels, commands, toolbar buttons, keybindings, and context menus; it leaves the global worker and app-wide contributions running. For a repository plugin, Run here actually unloads that project instance. Folder trust is a separate control. See Project Plugin Trust & Management.
Where plugin contributions appear
Contributions are read from the manifest eagerly at startup, before any plugin code runs, so a plugin's commands and panels are in the palette even when the plugin itself has not activated yet. Plugins are lazy by default: the entry module is imported the first time one of its contributions is actually used.
- Commands appear in the command palette under the plugin's own category, and can be bound to keys like any built-in action. See Palettes and Menus.
- Panels appear in the new-panel palette and open into the grid alongside terminals and viewers. See Terminals and Panels.
- Toolbar buttons collect into a single grouped plugin tray button rather than each claiming a top-level slot. You promote the ones you use to their own slot by hovering the tray row and clicking the pin, from Settings > Toolbar. Placement is your call, not the manifest's.
- Menu and context-menu items are appended below Daintree's own entries on the surfaces they target.
- Agents, MCP servers, and skills join the same rosters the built-ins use. See Agents and MCP Server.
- Cloud providers appear under Settings → Hosts → Cloud providers beside the built-in ones, so Daintree can create, start, stop and delete cloud machines on another provider. Daintree asks your consent once per plugin, before its first credential form. See Providers From Plugins.
What a plugin can and cannot do
The main entries of user-installed plugins run out of process, in a forked utility process with their own module realm and OS-level crash isolation. Host operations and registrations cross a MessagePort and return promises. React views run in Daintree's renderer. Built-in plugins activate their main entries in-process.
The manifest's capabilities array discloses intent and drives host-side policy. High-risk capabilities and compound combinations can elevate an action to confirmation; a command can narrow that derivation with requires. Host-mediated filesystem and Git calls enforce declared roots, and plugin-hosted MCP tools are subject to capability-derived danger limits. Network and socket allowlists describe intent; they do not constrain raw Node calls.
The normal worker runtime is not a security sandbox. A plugin's entry module can call Node directly. React views execute in the app renderer, so the worker's crash isolation does not cover every part of a plugin. Archives are unsigned and publisher identity is not verified. Read Trust & Capabilities for the full boundaries.
Writing a plugin
The shared authoring references cover both plugin origins; individual contribution points state where project scope differs:
- Plugin Manifest: every field in
plugin.json: identity and the plugin id format, version compatibility, capabilities and scopes, activation events, and how strict validation reports mistakes. - Contribution Points: the contribution types, including recipes, project-only surfaces, and the scope restrictions on each.
- Host API: the
activate(host)entry point, the runtime surface it hands you, and the view component contract. - Plugin UI Kit & Styling: host controls, themed layout, icons, view cleanup, and performance checks.
- Building & Distributing: the
daintree-pluginCLI, the hot-reload development loop,.dntrpackaging, and how to ship it.
Built-in plugins
Daintree ships several integrations as built-in plugins rather than as app code. GitHub, GitLab, Jira, Linear, and Beads each register a forge provider; GitHub also registers a file-decoration provider that badges review state on changed-file rows in the Review Hub, and is the reference implementation for what a real provider looks like. The Markdown editor and CSV viewer add file editors to the file viewer.
Built-in plugins can be disabled but not uninstalled. The switch works exactly as it does for anything else, and disabling GitHub takes its forge provider and decorations out of the app; there is simply no directory to delete, because they live inside the application bundle. They also carry no source badge, since built-in is the default.
The daintree.* namespace is reserved. A user-installed plugin whose name starts with daintree. is rejected at manifest validation.
Source references: plugin loading, archive installation and updates, and project controls, reviewed at the October 13, 2026 revision.