Skip to main content

Contribution Points

Every slot a Daintree plugin can fill: commands, menus, toolbar buttons, launch entries, layouts, search, panels, sidebar and Canopy views, settings, accounts, agent tools, databases, prompt templates, terminal links, themes, providers, file editors, and project surfaces, with scope rules.

Updated
Reviewed

A contribution point is a slot in Daintree that a plugin can fill. All of them are declared in the contributes object of plugin.json. The schema has thirty-four contribution arrays and four objects: surfaces, account, services, and assistantKnowledge.

This reference describes the current host contract. The npm 0.1.0 authoring packages predate several fields below; use the source SDK and CLI for current types and validation. See the authoring toolchain.

Daintree registers allowed contributions from the manifest before activation. Installed plugins load at startup; repository plugins also require project trust and staged activation when applicable. Your entry module is imported later, the first time one of these contributions is actually used. Installed contribution ids normally use the plugin namespace. Project plugins additionally use an instance-specific namespace; write manifest action references as publisher.name.command and let the host qualify them.

Scope availability

Project-level plugins can use most contribution points, and each one they declare reaches only their own project. The manifest rejects the groups that still land in an app-wide registry with no way to keep the contribution inside one project: menu items, agents, process tools, MCP servers (unless an agentMcp endpoint bridges every one), themes, forge providers, cloud providers, project templates, and Canopy views. An installed package with "instanceMode": "project" takes the same restrictions and may declare "project" databases; the Installed column below describes an app-wide installed plugin. Installed plugins may use the app-wide groups, but cannot claim project surfaces, declare a "project" database, or give a file editor paths. A slot-backed file editor requires a built-in plugin, and a forge provider only works from one.

ContributionInstalledProjectBuilt-in
commands, keybindings, contextMenus, toolbarButtons, launchEntries, layouts, searchProviders, panels, views, settings, setup, account, connections, servicesYesYesYes
agentMcp, assistantKnowledge, skills, promptTemplates, terminalLinks, contextProviders, recipes, tours, fileDecorationProviders, worktreeSetupSteps, worktreeDeleteNotes, elementPickerProvidersYesYesYes
databases"local" only, unless instanceMode is "project"Yes"local" only
fileEditorsView-backed, matched by extensionView-backed, by extension or pathsYes, including slot
surfacesNoYesNo
mcpServersYesOnly servers an agentMcp endpoint's source bridgesYes
menuItems, agents, processTools, themes, projectTemplates, canopyViewsYesNoYes
forgeProvidersListed, but unavailable: the implementation never bindsNoYes
cloudProvidersYesNoYes

Each rejection is a manifest error that names the reason, not a silent drop. The previewTools and guestAdapters contribution points were retired: a manifest that declares either is rejected as an unknown key from any origin. The built-in Element Picker replaced the preview tool they backed, and a plugin now extends it with Element Picker providers.

Filtering needs JavaScript. The contents list works without it, and so does your browser's find-in-page — every contribution point on this page is in the document.

Commands

Commands are callable actions. They appear in the command palette and can be bound to keys, toolbar buttons, menu items, and context menus.

"commands": [
  {
    "id": "plan-from-issue",
    "title": "Plan From Issue",
    "description": "Turn a Linear issue into a branch and agent session.",
    "category": "Linear Planner",
    "kind": "command",
    "danger": "confirm"
  }
]
FieldRequiredNotes
idyesBare command id, up to 64 characters.
titleyesPalette entry label.
descriptionyesOne-line summary shown under the title in the palette.
categoryyesSub-label on the command's row, up to 40 characters. The palette already groups your commands under your display name, so this only tells them apart inside that group. A built-in category id such as worktree or git is refused.
kindyes"command" or "query".
dangeryes"safe" or "confirm". "restricted" is rejected: a plugin cannot self-register a restricted action.
keywordsnoExtra palette search terms.
whennoA context expression over your plugin's own keys. While it is false the command is left out of the palette.
enablementnoSame grammar. While it is false the command stays in the palette, disabled with a reason.
inputSchemanoJSON schema validated against the dispatched args.
resultSchemanoJSON schema rooted at type: "object" that every result is checked against. A mismatch fails the dispatch, and the schema is published as the action's output schema.
assistantReachno"confirm-only" offers the command to the project's Daintree Assistant as a tool. Only valid beside "danger": "confirm", so the Assistant's calls meet the confirmation dialog unless the user has told it not to ask.
requiresnoThe capabilities this command uses. See below.

when and enablement shape the palette only. Keybindings, context menus, MCP, and host.dispatch never evaluate them, so they decide what is offered, not what can run.

requires: per-action capability intent

By default the host derives a command's effective danger from your plugin's entire capabilities list. Declare shell:exec for one command and every other command in the plugin inherits the confirmation dialog, including a no-argument "open the panel". Dropping the capability is not an honest fix. requires is.

{
  "id": "open-panel",
  "title": "Open Panel",
  "description": "Opens the tools panel.",
  "category": "Flutter Tools",
  "kind": "command",
  "danger": "safe",
  "requires": []
}
  • Omit it and nothing changes: the whole manifest is consulted, as before. Existing plugins need no migration.
  • [] declares that the command exercises no capability, so it stays one click even in a plugin holding shell:exec.
  • ["git:read"] consults only those capabilities, for both the high-risk set and the compound lattice.

Three things it does not do. It grants no access: host APIs still gate on the manifest's capabilities at call time, so listing one here neither adds nor removes runtime authority. It cannot lower a self-declared "danger": "confirm". And every entry must also appear in capabilities; naming one you did not declare fails the command's registration outright rather than falling back, so a typo surfaces at load instead of quietly reverting.

Binding a handler

Two styles, and the choice is not stylistic: it decides whether your handler can reach the host API.

Filesystem convention, installed plugins only. A command with id plan-from-issue looks for src/plan-from-issue.js or src/plan-from-issue.mjs, probed in that order, under the plugin directory. Its default export is the handler. The module is not imported until the command is first dispatched, so twenty declared commands cost nothing at activation.

// src/plan-from-issue.js
export default async function planFromIssue(args) {
  // handler body
}
Warning
A convention handler receives args and a read-only dispatch context, but no host argument, so it cannot call host.showQuickPick, host.settings.get, or anything else on the host. Use imperative registration when the command needs the live host. Project plugins always register handlers from their compiled worker entry; the host does not import a repository convention handler from src/. The handler must also ship as JavaScript: .ts and .tsx files are not probed. Compile to src/{id}.js.

Imperative registration binds a handler that closes over the live host. For a lazy plugin, also declare the command in the manifest; otherwise nothing makes that command reachable to trigger activation:

export async function activate(host) {
  await host.registerAction(
    {
      id: "plan-from-issue",
      title: "Plan From Issue",
      description: "Turn a Linear issue into a branch and agent session.",
      category: "Linear Planner",
      kind: "command",
      danger: "confirm"
    },
    async (args) => {
      // handler body, with `host` in scope
    }
  );
}

An imperative registration for the same id supersedes the convention file, so you can start with a manifest-declared stub and graduate the moment you need host access. A declared command with neither a matching file nor an imperative override produces a visible toast when run: Command "{pluginId}.{id}" has no handler. That is deliberate: the manifest entry alone is enough to make the command appear so you can wire it up incrementally.

A command whose resolved id collides with a built-in Daintree action is rejected at load and does not register. Pick a different id. See Host API for the full registerAction signature.

Keybindings

"keybindings": [
  {
    "actionId": "acme.linear-planner.plan-from-issue",
    "combo": "Cmd+Shift+P",
    "scope": "global",
    "when": "!terminalFocused && !modalOpen"
  }
]
FieldRequiredNotes
actionIdyesFully qualified, usually one your plugin declared.
comboyesSame normalized format as Daintree's own bindings. Chords such as "Cmd+K Cmd+S" work.
scopeno"global" (default), "worktreeGrid", or "dev-preview". Unknown scopes are rejected. The retired "portal" scope still validates so an older manifest loads, but a binding under it never fires and is not moved to another scope; validation and plugin diagnostics say so. The former terminal, modal, and worktreeList scopes were removed. Use a when condition instead.
descriptionnoWhat the binding does.
whennoContext expression, evaluated live on each keydown.

The when grammar

Expressions support &&, ||, !, ==, !=, and single-quoted string literals. Every renderer when (keybindings, context menus, toolbar buttons, launch entries, sidebar views) sees the project keys, which update live:

KeyTypeMeaning
isGitBackedbooleanThe project is a git repository.
workspaceKindstring"project", "scratch", or "" when no workspace is open.
activeSidebarViewstringThe sidebar view the project shows: "worktrees" or a sidebar view's id.
presentation*stringOne key per presentation feature, such as presentationForgeStats, presentationGitDetail, or presentationLauncherAgents: the project's level for it, "shown", "demoted", or, where the feature allows, "hidden".

They also see the keys plugins publish with host.setContext, under each plugin's manifest name: setContext("synced", true) from acme.tracker reads as acme.tracker.synced. Keybindings add the focus and UI keys:

KeyTypeMeaning
terminalFocusedbooleanKeyboard focus is inside a terminal.
textInputFocusedbooleanKeyboard focus is in an input, textarea, or editable element, excluding a terminal's own textarea. Added by the Linux release update.
modalOpenbooleanA modal dialog is open.
paletteOpenbooleanAny palette is open.
paletteIdstringIdentifier of the open palette, or "" when none.
fleetArmedbooleanAt least one terminal is armed for fleet broadcast.
fleetWaitingbooleanAt least one armed terminal's agent is waiting.
sidebarVisiblebooleanThe worktree sidebar is visible.
canopyHiddenbooleanCanopy is turned off, so nothing opens it.
dictationActivebooleanVoice dictation is starting, running, paused, or finishing, in this view or another.
voiceSendWaitingbooleanA prompt sent with Stop and send is still waiting on its dictation's cleanup in this view.
Warning
An unknown identifier evaluates falsy, which makes negated expressions permissive: a misspelled !modalOpne is always true and your binding fires everywhere. Spell-check the identifiers; nothing else will.

Bindings register when the plugin loads and unregister on unload. Plugin bindings are low priority and yield to user overrides and to conflicting bindings resolved by Daintree's keybinding service. See Keyboard Shortcuts for the built-in map.

Entries in Daintree's application menus.

"menuItems": [
  {
    "label": "Plan from Linear…",
    "actionId": "acme.linear-planner.plan-from-issue",
    "location": "view",
    "accelerator": "Cmd+Shift+L"
  }
]
FieldRequiredNotes
labelyesMenu entry label.
actionIdyesFully qualified action to dispatch.
locationyes"terminal", "file", "view", or "help".
acceleratornoAn Electron accelerator, passed through as written except that Cmd/Ctrl becomes CommandOrControl. Write "Cmd/Ctrl+Shift+L" for Cmd on macOS and Ctrl on Windows and Linux; a bare Cmd is the Command key only.
whennoEvaluated once at menu build time against an empty context, so only constant expressions are useful. For a live condition, gate a keybinding instead.

Context menus

"contextMenus": [
  {
    "actionId": "acme.linear-planner.link-issue",
    "location": "worktree",
    "label": "Link to Linear issue…"
  }
]

Locations are worktree, terminal, file, browser (the page-actions menu of a browser or dev preview panel), and project (the toolbar's project pill). On worktree, file, and project menus, plugin items sit in an Extensions submenu, grouped and labeled by plugin when more than one contributes, so the root menu keeps the same shape however many plugins are installed. On the terminal menu they follow Daintree's own entries.

A context-menu when clause sees the project keys and plugin keys above, plus the clicked surface's own keys: worktreeId on a worktree; panelId, panelKind, and worktreeId on a terminal; panelId and panelKind on a browser; projectId on the project pill; and none of its own on a file row. An identifier that names no key is falsy, so missing hides the item and !missing shows it everywhere; an expression that fails to parse hides it.

Every location dispatches its action with the clicked subject: { worktreeId }, { panelId, panelKind, worktreeId }, { panelId, panelKind, url } (with any credentials removed from the URL), or { projectId }. Only ids and the page URL are passed, never terminal output.

The file location is the interesting one: it is mounted on every file row Daintree renders, including the Review Hub's changed-file rows, the worktree card's changed-files list, the File Browser's tree and listing, the Diff Viewer's file sidebar, and the right-click menu on a file's own content. One contribution reaches all of them with no per-surface work, and the action is dispatched with { path, isDirectory, relativePath, worktreePath, status }. path is always absolute; isDirectory is always present, and relativePath, worktreePath, and status are each omitted when the row has no worktree root or no git status.

A file item can also narrow which rows it appears on, evaluated per row and combined with when: kind ("file" or "folder"), extensions (bare lowercase suffixes), and paths (globs relative to the worktree root). The three fields are rejected on any other location, and extensions is rejected beside kind: "folder".

Two built-in actions pair well here. file.openDiff opens the side-by-side diff for the dispatched file, and panel.openPluginPanel spawns or focuses one of your panels, passing initialArgs straight through to the view, so a context-menu item can open your panel already scoped to the file the user clicked.

Toolbar buttons

"toolbarButtons": [
  {
    "id": "plan-button",
    "label": "Plan",
    "iconId": "list",
    "actionId": "acme.linear-planner.plan-from-issue",
    "priority": 3
  }
]
FieldRequiredNotes
idyesBare id, namespaced at runtime.
labelyesHover tooltip.
iconIdyesOne of the shared plugin icon IDs below, or a ./…svg path to the plugin's own icon. Agent brand ids do not resolve here.
actionIdone of actionId, popover, or menuFully qualified. Built-in actions such as terminal.new work too.
popoverone of actionId, popover, or menu{ "viewId": "…" }: open one of your non-PTY panel views in a popover anchored to the button, instead of dispatching an action. Not combined with actionId or menu.
menunoUp to five of your own actions, each { actionId, label? }. Beside an actionId the button becomes a split button; on its own it is a menu button.
priorityno1 to 5, lower sorts earlier within your plugin's tray group. Default 3.
whennoContext expression deciding whether the button shows, evaluated live. While it is false the button leaves the tray and the toolbar; a promoted button returns to its slot when the clause is true again. The action stays reachable elsewhere.

A popover is drawn by the host, at most 450 by 500 pixels, and the view mounts fresh on each opening with hostContext.kind set to "popover" and a hostContext.close() to dismiss it. It has no panel record behind it, so persistState and initialArgs go through the durable view-state store. Use host.setToolbarButtonState to show a button as on, busy, or disabled rather than hiding it.

The plugin tray

Contributed buttons do not each claim a top-level toolbar slot. They collect into a single plugin tray button, grouped by owning plugin. From the tray a user promotes an individual button to its own slot (hover the row and click the pin, or use Settings > Toolbar), and a promoted button keeps its tray row as well.

This is deliberate. Placement is the user's call, not the manifest's: there is no field that requests a top-level slot, so five installed plugins cannot between them consume the entire toolbar. See UI Layout for the toolbar itself.

Launch entries

Rows in the launcher: the dock's +, its right-click menu, the grid's right-click menu, and the toolbar launcher. Each entry opens one of your panels, runs one of your commands, or starts an agent with a first prompt. Your entries form one group under your plugin's name, and the user can pin any of them to its own toolbar button or hide the group in a project.

"launchEntries": [
  {
    "id": "new-record",
    "label": "New record…",
    "iconId": "plus",
    "panel": { "id": "records", "args": { "mode": "new" }, "placement": "dialog" }
  },
  {
    "id": "chat",
    "label": "Chat with the records agent",
    "iconId": "sparkles",
    "agent": { "id": "claude", "prompt": "Read RECORDS.md, then wait for my question." }
  }
]
FieldRequiredNotes
idyesBare id, namespaced at runtime. It also keys a pinned toolbar button, so renaming it unpins the entry.
labelyesUp to 80 characters. Write it as the action.
iconIdyesA shared plugin icon id or a ./…svg path.
descriptionnoUp to 200 characters, shown as a tooltip and searched.
priority, whennoOrder within your group (1 to 5, default 3) and a live visibility clause, as on a toolbar button.
showInEmptyStatenoAlso list the entry as a tile in the stock empty-canvas launcher.
panelone target{ id, args?, placement? }. id names one of your own panels; args (at most 8 KB of JSON) reaches the view as initialArgs; placement is "dock", "grid", or "dialog".
commandone target{ actionId, args? }, one of your own actions.
agentone target{ id, prompt }: start that agent with prompt (up to 4,000 characters, not starting with -) as its first turn, on the user's own preset. No flags, environment, or preset are the plugin's to choose.

An entry declares exactly one target. A panel or command target must be your own, and a placement the panel cannot take (the dock for dockable: false, the grid for a project panel, a dialog or args for a PTY panel) is refused. Entries run only when the user picks the row or its pinned button, never from the palette, MCP, or an agent. At most 20 per plugin.

Layouts

A named arrangement of your panels, browser pages, and recipes. The user applies one from the command palette (Apply layout: {name}), and your own commands can apply yours with host.dispatch("layout.apply", { layoutId }).

"layouts": [
  {
    "id": "workspace",
    "name": "Records workspace",
    "entries": [
      { "panel": "records", "tabGroup": "main", "maximized": true },
      { "panel": "notes", "tabGroup": "main" },
      { "recipe": "agent" },
      { "browser": "http://localhost:3000", "location": "dock" }
    ]
  }
]

Each layout has an id, a name of up to 80 characters, and 1 to 12 entries. An entry names exactly one of panel (one of your own non-PTY panels), browser (an http: or https: URL), or recipe (one of your own recipes), and may add location ("grid" or "dock"), tabGroup (entries sharing a key become tabs of one group), and maximized (at most one per layout, in the grid). No target may appear twice, and a tab group needs at least two panels in the same place and of the same panel scope.

Applying a layout is additive: it opens what is missing and moves, groups, and maximizes what it lists, and never closes anything. Undo layout change puts back what it moved. A layout that runs a recipe first shows the user every terminal it will start and applies only on approval. Your commands can apply only your own layouts; MCP clients and agents cannot apply layouts at all. At most 20 per plugin.

Search providers

A search provider makes your plugin's content findable from the quick switcher. Typing the provider's keyword and pressing Tab scopes the switcher to it; with blend: true a few results also appear below the built-in ones in the unscoped search. Picking a result opens one of your panels with the result's arguments or dispatches one of your commands with them.

"searchProviders": [
  {
    "id": "notes",
    "kind": "declarative",
    "title": "Notes",
    "keyword": "notes",
    "blend": true,
    "query": "find_notes",
    "target": { "panel": "notes" }
  },
  { "id": "people", "kind": "runtime", "title": "People", "keyword": "people" }
]
  • "declarative" answers without your plugin running. query names one of your database's declared read queries with exactly one string parameter, which receives what the user typed, and target ({ panel } or { command }) says where results open. Alias the columns to id, label, and optionally description, iconId, and args (a JSON object as text, such as SQLite's json_object()).
  • "runtime" is a function bound in activate() with host.registerSearchProvider, returning { id, label, description?, iconId?, target?, args? } with args as an object. A result needs its own target when the declaration has none. It receives an abort signal for superseded queries.

keyword is 1 to 24 lowercase letters, digits, or hyphens, starting with a letter. Keywords are first come, first served: a later plugin claiming the same keyword in a project is refused there and told which plugin holds it, and Daintree's own file search holds files. Each provider has one second per query; a blended search never starts a plugin that is not already running. Every result is checked host-side, and the user can switch each provider off with Show in quick switcher in the plugin's settings. At most 5 per plugin.

Panels

A panel is a full-sized workspace in Daintree's grid, alongside terminals, viewers, and the Review Hub. The panel entry declares the slot; the view below provides the component that fills it.

"panels": [
  {
    "id": "dashboard",
    "name": "Cost Dashboard",
    "iconId": "gauge",
    "color": "hsl(150 60% 55%)",
    "showInPalette": true
  }
]
FieldRequiredNotes
idyesBare id, namespaced at runtime as the panel kind.
nameyesLabel in the panel header and palette.
iconIdyesA shared plugin icon ID, a ./…svg path to the plugin's own icon, or a built-in agent id to render that agent's brand mark.
coloryesAccent color for the panel tab.
hasPtynoDefaults to false. true uses the terminal host instead of a React view. A matching view declaration is ignored; panel menus can still carry the plugin's own actions.
dockablenoDockable unless you declare false. Declaring false alongside hasPty: true is a manifest error, because the opt-out could never be honored.
canRestartnoShow a restart control in the panel header.
canConvertnoAllow conversion between compatible kinds. Rarely useful for a plugin.
showInPalettenoInclude in the new-panel palette. Default true.
scopeno"worktree" (the default) ties each panel to the worktree it was opened in. "project" makes it one panel for the whole project, opened in the dock with no worktree and shown in every worktree. Not allowed with hasPty: true or dockable: false.
reportsActivitynotrue lets the plugin report its own work on panels of this kind with host.setPanelActivity, drawn like agent activity and attributed to the plugin. Without it the method refuses this kind.
menunoUp to five of your own actions, shown in the panel's ⋯ and right-click menus in the order given. Each entry is { actionId, label? }; the label defaults to the action's title.
toolbarnoUp to three of your own actions drawn as buttons in the panel header. Each entry is { actionId, label?, iconId?, status? }. Without an icon the label is drawn as text. Not allowed on a hasPty panel.
stateVersionnoInteger version of the shape this panel saves through persistState. The host stamps it on every write, tells the view which version it is reading, and refuses to hand over state written by a newer build of the plugin. Bump it only for an incompatible change.

Panel menus and toolbars

menu and toolbar accept only your plugin's own actions, written publisher.name.id, and when you declare commands each must match one of them. An entry appears while its action is registered and is dispatched with { panelId } naming the panel it was used on. The view sets a toolbar button's live state (busy, disabled, a tone, a short status text, an "Updated" age) at runtime, and a plugin can publish further menu entries while it runs. A PTY panel can take menu entries, which appear in the terminal's right-click menu, but not toolbar entries. See Host API for the runtime calls and Plugin UI Kit & Styling for how they look.

Icon IDs

One shared set backs every surface that renders a plugin icon (the panel palette, panel headers, tabs, the dock, toolbar buttons, the toolbar overflow, and process-tool tabs), so an id looks the same everywhere. The developer set:

terminal, package, puzzle, globe, monitor, monitor-play, file-text, file-diff, folder-tree, git-branch, git-pull-request, sticky-note, gauge, list, sparkles, layout-panel-top, daintree

App-shaped glyphs for project tools that stand in for a whole application:

wallet, receipt, chart-column, chart-line, chart-pie, calendar, clock, kanban, check-square, list-todo, users, contact, handshake, briefcase, inbox, mail, image, palette, book-open, bookmark, notebook, newspaper, megaphone, target, heart-pulse, flame, dumbbell, utensils, tag, shopping-cart, boxes, database, table, layout-grid, map, star, rocket, lightbulb, flask

Verbs for toolbar actions: refresh-cw, download, upload, filter, plus, search, play, settings.

An unrecognized icon id falls back to a generic glyph without failing manifest validation, so a manifest written for a newer host degrades on an older one. That says nothing about compatibility of the plugin's other fields or APIs. daintree-plugin validate warns about ids your installed host does not know. Manifest icon ids are this list only; they are not looked up by Lucide name.

Your own SVG icons

A panel, a panel toolbar entry, a toolbar button, a launch entry, a sidebar view, a search provider, an agent, or a process tool can name an SVG file the plugin ships, written as a relative path in iconId: "iconId": "./icons/ledger.svg". The path must start with ./, end in .svg, be lowercase, stay inside the plugin directory, and be at most 64 characters; the file may be at most 64 KiB. The host reads and sanitizes the markup, and daintree-plugin validate runs the same checks, reporting a broken file as an error. Because the path lives in the existing iconId field rather than a new key, an older host simply shows the fallback glyph.

Live panel-title badges

A plugin can put a badge in its panel's title chrome at runtime with host.setPanelBadge(panelId, badge), and clear it by passing null. Two shapes:

await host.setPanelBadge(panelId, { kind: "dot", color: "warning", tooltip: "3 checks failing" });
await host.setPanelBadge(panelId, { kind: "label", text: "12", color: "success" });

color is default, success, warning, or error; success renders as neutral emphasis rather than green, because the host cannot know what a given plugin means by success. tooltip is optional and capped at 200 characters. A label is at most six characters, and one that exceeds the cap is rejected rather than truncated, so it can never overflow the header. This is a live push, not a manifest field: it is how a long-running build or review-status plugin reports state without opening its panel.

Views

A view is a React component the plugin renders. A location: "panel" view binds to a panel slot by matching its bare id; at load, that panel kind gains a componentPath resolved to a plugin:// URL, and the renderer host lazy-imports the module under an error boundary. Three other locations name no panel: "settings", "sidebar", and "fileEditor".

"panels": [
  { "id": "dashboard", "name": "Cost Dashboard", "iconId": "gauge", "color": "var(--theme-category-orange)" }
],
"views": [
  { "id": "dashboard", "componentPath": "./dist/dashboard.js", "location": "panel" }
]
FieldRequiredNotes
idyesFor a panel view, must match a panels entry's id. A panel view with no matching panel is a manifest error: it could never be shown. A settings, sidebar, or file editor view must not share an id with a panel.
componentPathyesPOSIX-relative path to a pre-built ESM module inside the plugin, whose default export is a React component. Absolute paths, URL schemes, and .. segments are rejected.
locationyes"panel", "settings", "sidebar", or "fileEditor".
iconIdnoA sidebar view's glyph in the switcher. On any other view it is accepted for compatibility but ignored: the matching panel owns the rendered icon.
name, priority, whensidebar onlyThe switcher entry: a name of up to 40 characters (required), a priority from -1000 to 1000 (default 0), and a live visibility clause. Rejected on other locations.
title, description, pagessettings onlyWhat settings search shows for the section, and up to 20 pages ({ id, title, description? }) the host lists and opens inside it. Rejected on other locations.

A location: "settings" view is the plugin's own settings section. A manifest may declare at most one. It mounts in the plugin's settings below the generated fields, and opening it can activate a lazy plugin. Mark a declared setting "editor": "view" when this view edits it, so the generated form does not show it twice.

A location: "fileEditor" view backs a view-backed file editor and mounts only inside the file panel.

Views ship as pre-built ESM. Nothing compiles TypeScript or JSX at load time. A panel view carries no name or description: the panel is the single source of truth for its display metadata. The full component contract (the props, the React hooks, and how module generations defeat the renderer's ESM cache) is on Host API.

A location: "sidebar" view sits in the sidebar beside the built-in worktree list. While at least one plugin sidebar view applies to the project, the sidebar heading becomes a switcher listing every view by priority; the worktree list is fixed at 0 and wins a tie. The user's pick is remembered per project. Until there is one, the sidebar opens on the highest-priority project plugin view, or the worktree list; an app-wide installed plugin's view shows only once the user picks it. A view whose plugin stops or whose when turns false gives way to that default until it applies again. Its when may not read activeSidebarView. The view mounts with hostContext.kind set to "sidebar" and should lay out for the sidebar's 200-pixel minimum width.

Canopy views

contributes.canopyViews offers one of your panel views in the Canopy window, which watches every project at once: the place for a tool that spans projects, such as an issue tracker across repositories. Each entry is { "viewId": "…" } naming a non-PTY location: "panel" view, at most five, each named once. Canopy lists it under Plugins below its inbox, and the same view stays a panel in every project window.

Naming a view is your word that it works with no project around it. In Canopy, hostContext.kind is "canopy" and there is no panel record, so worktreeId, setTitle, and the panel toolbar and menu setters are absent. persistState and initialArgs keep one bag per view for the Canopy window. Dispatching an action from the view fails, because actions run in a project window; call your own backend instead. Only an app-wide plugin may declare one.

Temporary unmount is not teardown

This is the distinction that most often bites. A panel outlives its views, and a view receives two abort signals that mean different things:

  • disposeSignal is the lifetime of this mounted view attempt. It aborts on unmount, on "Try again" after a render error, and when the host drops the panel kind. Crucially it also aborts on a temporary unmount: maximizing a sibling pane, leaving a dock tab, or backgrounding a project view.
  • panelRemovedSignal is the lifetime of the panel record. The same object is handed to every mount of a given panel, so it survives remounts, retries, trash-then-restore, and plugin upgrades. It aborts exactly once, when the panel is permanently removed.

Deciding deletion from disposeSignal alone is how a plugin ends up killing a running dev-server session because someone maximized the pane next door. Tie view-scoped work (in-flight fetches, DOM observers, timers driving the UI) to disposeSignal. Tie anything that should survive being backgrounded but not survive the panel to panelRemovedSignal. Keep genuinely durable resources such as spawned processes in the plugin worker and release them from host.onDidChangePanelLifecycle on the "removed" phase, because the worker observes the panel across every remount and the view cannot.

Settings schema

Declares user-configurable settings. Daintree generates the form; you read values back through the host API.

"settings": [
  {
    "id": "linear.apiToken",
    "type": "secret",
    "scope": "user",
    "label": "Linear API Token",
    "description": "Personal API token from linear.app/settings/api"
  },
  {
    "id": "linear.defaultTeam",
    "type": "string",
    "scope": "project",
    "label": "Default team",
    "default": ""
  }
]
FieldRequiredNotes
idyesLimited to letters, digits, ., -, and _, so it can always be referenced by a ${settings:id} token.
typenoOne of nine (see below). Defaults to string.
label / descriptionnoField label and help text.
defaultnoDefault value.
scopeno"user", "project" (in the repository), or "local" (this machine and project, outside the repository). Defaults to "user".
optionsnoNon-empty string array. Required when type is enum.
min / maxnoBounds for number. min may not exceed max.
mustExistnoFor the path types: flag a stored path that no longer resolves. Advisory: it never blocks saving.
extensionsnoFor file only, no leading dot: ["json", "md"]. Rejected on any other type.
secretnoLegacy boolean. true normalizes to type: "secret". Prefer the type.
requirednoMarks a value the plugin cannot work without. An unset required setting puts a "needs setup" strip on the plugin's panels, and host.settings.missingRequired reports it.
editorno"form" (the default) or "view". "view" leaves the field out of the generated form because the plugin's settings view edits it.

A secret may not declare a default: it would ship in plugin.json. Leave it unset and mark it required instead.

The nine types are string, number, boolean, enum, json, secret, path, directory, and file.

  • secret is encrypted at rest through the OS keychain, transparently to the plugin, and never written to the repository, even at project scope. Where no keychain is available the value is not saved and the form says why. See Trust & Capabilities for the caveats.
  • path and directory render a read-only input plus a native folder chooser; file opens a single-file chooser narrowed by extensions. The stored value is an absolute path, read back like any other setting.

Each field has one home. An installed plugin's user fields are on its Settings tab in the Plugin Manager, and its project and local fields are in Project settings > Plugins; a project plugin's fields are all in Project settings. Changes fire a subscription callback, so a plugin never needs to reactivate to pick up an edit.

const token = await host.settings.get("linear.apiToken");

Setup checklist

contributes.setup is a short list of what the plugin needs before it is useful: connect an account, choose a default, run a first sync. Daintree shows it on the plugin's panels as "Acme setup · 1 of 3" while a step is outstanding and lists the steps at the top of the plugin's settings.

"setup": [
  { "id": "connect", "title": "Connect your Acme account", "done": { "kind": "account" } },
  { "id": "workspace", "title": "Choose a workspace", "done": { "kind": "setting", "key": "workspace" } },
  {
    "id": "sync",
    "title": "Run the first sync",
    "done": { "kind": "context", "when": "acme.tracker.synced" },
    "action": { "kind": "command", "actionId": "acme.tracker.sync" }
  }
]

Each step has an id, a title of up to 80 characters, an optional description, a done condition, and an optional action. Done is observed, never stored: a setting step is done once the declared setting has a stored value (a default does not count), an account step once the named connection (or the project's) is connected, and a context step while its when clause holds over plugin context keys. There is no API to mark a step done. An action opens the plugin's settings ({ "kind": "settings", "key"? }) or runs one of your own commands with no arguments. The user can Skip a step, remembered per project. Nothing opens on its own. At most 10 steps.

Accounts and connections

contributes.account declares one online account the host signs in to on the plugin's behalf; contributes.connections declares up to eight named ones (each the same shape plus an id), for a plugin that talks to several services or keeps several accounts. Declare one or the other, never both. Declaring an account either way requires network:fetch.

"account": {
  "kind": "oauth2",
  "label": "Acme",
  "authorizeUrl": "https://acme.example.com/oauth/authorize",
  "tokenUrl": "https://acme.example.com/oauth/token",
  "clientId": "daintree-acme",
  "scopes": ["read"],
  "identity": { "url": "https://api.acme.example.com/me", "field": "login" }
}
  • "kind": "oauth2" runs an authorization-code flow with PKCE as a public client through a 127.0.0.1 loopback redirect. "kind": "token" asks the user to paste an API token.
  • Both take a label, an optional description, an optional identity ({ url, field }, a bearer GET whose JSON names the account at the dotted field), and an optional test ({ url }, run by the row's Test button). Every URL must be public https: with no credentials or fragment.
  • The host draws the Connect and Disconnect rows, stores the tokens encrypted with the operating system's secure storage, and gives the plugin only a current access token through host.account.

Services

contributes.services lets cooperating plugins call each other through declared interfaces. provides (up to 16) declares services others may call, each { name, version, methods }: name is your plugin id plus one segment, version is a semver version, and methods lists up to 32 method names bound with host.registerService. requires (up to 16) declares services this plugin calls, each { name, range, optional? }. Nothing is installed or loaded in order because of either list; imports resolve when called. To say which other plugins yours is meant to work beside, use the manifest's worksWith.

MCP servers

Model Context Protocol servers the plugin ships, with Daintree as the client. The Plugin Manager lists, restarts, and inspects an app-wide plugin's servers, but their tools are not merged into what agents in your terminals see. To give agents a contributed server's tools, name them one by one in an agentMcp endpoint's source; to serve tools of your own, register them on that endpoint instead. See MCP Server.

"mcpServers": [
  {
    "id": "linear",
    "name": "Linear MCP",
    "command": "node",
    "args": ["./dist/mcp/linear-server.js"],
    "env": { "LINEAR_API_KEY": "${settings:linear.apiToken}" }
  }
]

command is an executable, typically node, python, or npx, resolved on PATH. args and env are optional; a relative path in args resolves against the plugin directory, which is always the server's working directory. Values in all three may reference a declared setting with ${settings:id}; an id naming no declared setting is a manifest error, not a runtime surprise. The token resolves at spawn time from the setting's stored user-scope value only, and an unset value becomes an empty string. Transport is stdio only: remote transports, explicit transport types, per-server working directories, and restart policies are all deliberately absent.

The server does not inherit Daintree's environment. It starts from a short allowlist (PATH, HOME, temp directories, locale, time zone, shell and user names, proxy and CA settings, and the Windows essentials) plus the env you declare, so an API token in Daintree's own environment never reaches it. Pass anything else the server needs through env, ideally from a secret setting.

Daintree supervises the process. It is lazily spawned the first time its tools are listed or called, hard-killed when Daintree exits, and on an unexpected crash it transitions to crashed and rejects the calls in flight. A crash is not respawned at once; the next listing or call starts it again, as a manual restart does, and a call bridged to agents backs off after repeated failures. Calls from Daintree's own MCP client run through a consent, permission, and audit subsystem, with each tool's danger tier taken from its MCP annotations and capped against the plugin's declared capabilities, and share a rate limit of a burst of 20, then one per second. Calls bridged to agents are checked against the project's grant for the endpoint instead.

Changing a user-scope setting automatically restarts every running or crashed server that references it, debounced by about a second so a burst of edits coalesces into one respawn. Servers that were never started stay stopped: a settings change never eagerly boots one.

Warning
A contributed MCP server is a real subprocess with your machine's privileges, spawned by a plugin. Treat it as trust-gated, not as inert manifest data.

Agent MCP tools

contributes.agentMcp is the inbound direction: tools your plugin serves to the agents running in Daintree's terminals. You write no server and pick no port. Daintree serves each plugin as one MCP server on its own loopback listener, named daintree-<mcpName> (see mcpName), and owns the transport, a per-terminal credential bound to one project, and revocation. Requires the mcp:expose capability. Allowed in project plugins as well as installed ones; at most one endpoint per plugin.

"capabilities": ["mcp:expose", "fs:project-write"],
"contributes": {
  "agentMcp": [
    { "id": "data", "name": "Household ledger", "description": "Read and append transactions.", "mode": "tools" }
  ]
}
FieldRequiredNotes
idyesThe endpoint id that host.mcp.registerTools binds a roster to. Not the server name.
nameyesUp to 80 characters, shown in the per-project access setting. Agents never see it.
descriptionnoUp to 400 characters.
modeyes"tools", the only mode.
groupsnoUp to 8 tool groups the user allows one at a time, each { id, name, description?, access } with access "read" or "write". With groups declared, every tool names its group.
sourceno{ mcpServer, tools }: serve tools from one of your own mcpServers, each listed as { name, serverTool, group?, description? }. Never a wildcard, so a tool the server adds later never reaches an agent unnamed.

The tools themselves are registered from activate() with host.mcp.registerTools(endpointId, tools), or bridged from source: up to 16 tools in all, counting the database queries the manifest declares, with names of up to 32 lowercase letters, digits, and underscores starting with a letter, input schemas that are enforced before your code runs, and results capped at 256 KiB with a 60-second call timeout. An agent listing or calling the plugin's own tools activates a lazy plugin. See Host API for the registration contract.

A plugin that declares a database also gets the host's own read-only database_schema and database_query tools on the same server, plus a tool for each of its declared queries, without mcp:expose; those names are reserved.

Nothing reaches an agent until the user allows it. Access is set per plugin in Project settings > Plugins > Agent tools: Off (the default), Read only (the database tools and declared read queries), or Read and write (those, declared write queries, and your own ungrouped tools). Tools in a declared group are allowed group by group. Daintree's MCP server must be on, and an agent receives the servers when it launches, so raising access reaches agents started afterwards while lowering it also cuts off running ones. A repository can set defaults for its own project plugins in .daintree/mcp.json; it can never turn on an installed plugin. See Trust & Capabilities.

Skills

Markdown instruction or knowledge files that extend Daintree's built-in MCP server. Agents discover and load them through its skills.search and skills.load tools.

"skills": [
  {
    "id": "tdd-workflow",
    "name": "TDD Workflow",
    "path": "./skills/tdd-workflow.md",
    "triggers": ["test-driven", "tdd", "red-green-refactor"]
  }
]

path is a relative path inside the plugin, realpath-contained at read time. triggers is an optional array of up to 50 search terms the agent uses to find the skill. The file's content is returned when an agent loads it; a file over 512 KiB is skipped with a warning. A plugin with an agent MCP server also serves its skills there. An app-wide plugin's skills reach every project; a project plugin's, or a per-project instance's, reach only sessions bound to its own project. Skills are inert declarative content and require no capability.

Assistant knowledge

contributes.assistantKnowledge is Markdown the Daintree Assistant is given about the plugin's agent tools: short instructions (a .md path), up to 16 skills (each { id, path } naming a folder that holds a SKILL.md), and up to 32 references (each { id, path } naming a Markdown file). It reaches the Assistant only while the user has given it the plugin's tools in that project, framed as the author's notes on those tools. It requires no capability, but the plugin must declare agentMcp or databases.

Prompt templates

Templates the agent composer's / menu offers under the plugin's name. Choosing one asks for its arguments, if any, then fills the draft for the user to edit and send. A template never submits.

"promptTemplates": [
  {
    "id": "reconcile",
    "title": "Reconcile this month",
    "description": "Match the month's ledger against the bank export.",
    "body": "Reconcile {{month}} for the {{account}} account and list anything that doesn't match.",
    "args": [
      { "name": "month", "label": "Month", "required": true },
      { "name": "account", "label": "Account" }
    ]
  }
]

title is up to 80 characters, description up to 300, and body up to 8,192. args holds up to 20 single-line fields, each { name, label, required? }, and every {{name}} in the body must name one. Values are inserted as typed, once. No capability is required.

Terminal text the plugin makes clickable: identifiers such as INV-0042 that agents print, or URLs on the plugin's own service. A match is underlined on hover and clicking it dispatches one of the plugin's own commands.

"terminalLinks": [
  { "id": "invoice", "pattern": "\\bINV-(\\d{4,8})\\b", "actionId": "acme.invoices.openInvoice" },
  { "id": "record", "url": { "host": "records.example.com", "pathPrefix": "/records/" }, "actionId": "acme.invoices.openRecord" }
]
  • Each entry declares pattern (a regular expression matched within one row, with optional ignoreCase) or url ({ scheme?, host, pathPrefix? } on one exact public host). actionId must be one of the plugin's own commands.
  • A pattern match dispatches { text, groups, panelId, panelKind, worktreeId? }; a claimed URL dispatches { url, panelId, panelKind, worktreeId? } instead of opening the browser.
  • Patterns are held to rules that keep backtracking bounded: at most 256 characters, no backreferences, lookarounds, or named groups, and a cap on the product of quantifiers. Matching runs off the terminal's thread, only on the row under the pointer, and built-in links win any overlap.
  • Only the matched text leaves the terminal, and only on a click. A matcher grants no terminal:read access and needs no capability. At most 20 per plugin.

Context providers

An @ context source the agent composer offers from the plugin's own data. A provider claims a short prefix such as rec; typing @rec: lists the provider's matches, and picking one leaves a chip in the draft. Nothing is read until the user sends, when the host asks the provider for the item's current content.

"contextProviders": [{ "id": "records", "prefix": "rec", "label": "Records" }]

prefix is one to sixteen lowercase letters and cannot be diff, terminal, selection, or notes; label is up to 60 characters. The implementation binds in activate() with host.registerContextProvider({ id }, { search, resolve }): a search has 3 seconds and returns at most 50 rows, and a resolve has 5. A chip that fails sends as a visible placeholder rather than holding the send. The first plugin to claim a prefix keeps it where both are visible. No capability is required. At most 10 per plugin.

Recipes

Plugins can ship named multi-terminal launch layouts in contributes.recipes. Each entry requires id, name (up to 200 characters), and 1 to 10 terminals; optional showInEmptyState and autoAssign are user-overridable defaults. Recipe ids are qualified as publisher.name.recipe. An installed plugin's recipes appear in every project; a project plugin's appear only in its own project.

A terminal's type is terminal, dev-preview, plugin-panel, a built-in agent id, or an agent the same plugin contributes. Entries take an optional title, command, environment, initial prompt, system prompt, arguments, dev command, and exit behavior; a plugin-panel step names one of the plugin's own panels in panelId and may pass panelArgs. A recipe may also declare variables its prompts use as {{plugin.name}}, filled when the plugin offers to run it with host.runRecipe, and requiresAgentTools, which refuses a launch that includes an agent step while the plugin's agent tools are off. Nothing starts until the user confirms.

Contributed recipes are immutable; Save to repo duplicates one into a team recipe to customize. Recipes require no plugin capability token, but they describe executable startup content and the archive preview discloses their names. See the recipe contribution types and PluginRecipeRegistry.

Worktree setup steps

Work the plugin does for each worktree Daintree creates, after the project's own setup script succeeds: provisioning a preview database, seeding fixtures, registering the branch with an outside service. Each entry is { id, label, timeoutMs? }, with a label of up to 80 characters and a timeout from 1 second to 30 minutes (5 minutes by default), and the handler binds in activate() with host.registerWorktreeSetupStep.

Steps run one at a time, by plugin id and then manifest order, and one step's failure does not stop the next. The worktree stays in setup until every step settles, so a first agent waits for them. The user allows each step once per project from the worktree card, and asks again after a new plugin version, label, or timeout. Steps run from the plugin as loaded for the project, never from the new worktree's branch. Nothing calls the step back when the worktree is deleted; a worktreeRemoved event route can wake the plugin instead. At most 10 per plugin.

Worktree delete notes

contributes.worktreeDeleteNotes adds the plugin's notes to a worktree's delete confirmation: things it knows that Daintree does not, such as unsynced edits or a preview deployment still running. Declare one entry, { "id": "…" }, and bind it in activate() with host.registerWorktreeDeleteNotesProvider. A plugin that has not answered within 3 seconds, activation included, is shown as not answering. Notes only annotate: they never cancel a delete or change its confirmation. No capability is required, and the user can turn a plugin's notes off.

Tours

A plugin can ship a narrated welcome tour that plays in the same dialog as the Daintree tour: a few short chapters, each an animated mockup with captions and optional voice-over. Without panelKind it is a plugin tour offered from Help and the command palette; with one it is a panel tour opened from that panel's menu, and panelKind must name one of the plugin's own panels. A project plugin's tours are offered only in its own project.

Each entry has an id, a title (up to 120 characters), a componentPath to the scene module, up to 32 chapters (each with an id, a duration of at most 600 seconds, named cues, captions, an audioUrl, and a narrationHash), and the audioHosts remote narration may be fetched from. audioUrl is a file shipped in the plugin, an HTTPS URL on a host the tour lists, or null. An optional version and a finish step ({ hint, action }, opening settings or running one of your commands) round it out. The scene module is imported only when the tour opens, and draws with the host-served @daintreehq/tour kit. The daintree-plugin tour commands that voice, align, and preview a tour are newer than the 0.1.0 CLI on npm. See the app's tour guide for the authoring workflow.

Project templates

Starting files for a new project, offered under Template when the user creates a project folder. Each entry is { id, title, description, iconId? }, and its files are the plugin's project-templates/<id>/ folder, copied as they are. The user sees every file before anything is written, and nothing in the plugin runs. A template is refused if it carries repository metadata, installed dependencies, or agent configuration and hooks. Installed and built-in plugins only; at most 10 per plugin.

Themes

App themes, offered in Settings > Appearance under the plugin's name. Each entry is { id, name, type, path }: type is "dark" or "light", and path names a JSON file of at most 128 KiB holding a palette in the shape of Daintree's built-in theme sources, plus optional tokens and extensions overrides. Validation is strict, and the contrast checks are a gate: a theme that fails any of them is never offered, and the reason goes to the plugin's log. If the plugin goes away, Daintree switches to the user's preferred built-in theme of the same polarity. Installed and built-in plugins only; at most 20 per plugin. See Theme Authoring for the palette model.

Project surfaces

contributes.surfaces lets a project plugin replace one of Daintree's own surfaces for its own project. It has three view slots, each { "viewId": "…" } naming a declared panel view with a matching non-PTY panel: emptyCanvas stands in for the stock launcher while the grid is empty, projectHome adds a Home the main area can show alone or beside the grid, and worktreeCreate replaces the New worktree dialog. defaultLayout names one of the plugin's own layouts to open on the project's first open on this machine, while the grid and dock are still empty; if the user has opened something first, it is offered instead, and its recipes wait for a click. One plugin owns each slot in a project, and Daintree always keeps a control that returns to its own surface. Installed plugins cannot make a surface claim. See Project Plugin Surfaces.

Databases

contributes.databases declares a SQLite file the plugin opens through host.db. The declaration names the file, discloses it, and decides where it lives, so the host can resolve and contain the path before plugin code sees it.

"databases": [
  { "id": "ledger", "description": "Household transactions, amounts in integer cents." }
]
FieldRequiredNotes
idyesBare id; also the default file name.
descriptionnoUp to 400 characters. Shown to agents by the database_schema tool.
locationno"project" (the default) or "local". A project database is a file in the repository, at .daintree/data/<manifestId>/<id>.db unless path says otherwise, and needs "scope": "project" (or "instanceMode": "project") plus fs:project-write. A local database lives in the plugin's own data directory on this machine.
pathnoProject databases only: a path relative to the project root, ending in .db, .sqlite, or .sqlite3, never inside .git.
journalModeno"delete" (the default) or "wal".
schemaVersionnoHow many migrations this version of the plugin applies. A writable open that passes a different number of migrations fails, so the declaration cannot drift from the code.
queriesnoNamed read or write statements served to agents as tools of their own. See below.

A declared query is { name, mode, description, params?, sql }: a tool name, "read" or "write", the description agents see, typed parameters (with optional JSON Schema constraints the host checks first), and one statement whose named placeholders bind to them. Agents pass values, never SQL. A read query runs on a fresh read-only connection once agent access is Read only; a write query (one INSERT, REPLACE, UPDATE, or DELETE) runs in its own transaction once access is Read and write. Neither starts the plugin. A query the host cannot serve safely rejects the manifest, and a plugin may declare at most 16 across its databases.

An app-wide installed plugin or a built-in plugin can declare only local databases, and must write "location": "local" because the default is "project". Its local file serves every project, so agent access to an installed plugin's database tools in one project reads what the plugin stored for all of them. Every panel of a plugin that declares a database gets a host-owned Back up data… menu entry that snapshots the databases the plugin has actually created to a file or folder the user picks. See Host API for opening, migrating, and querying.

Agents

Teaches Daintree about a launchable agent CLI it does not ship, so it appears as a named, selectable agent rather than a generic shell. Requires the agent:register capability, which the manifest gate enforces.

"capabilities": ["agent:register"],
"contributes": {
  "agents": [
    {
      "id": "acme",
      "name": "Acme Agent",
      "command": "acme",
      "args": ["--interactive"],
      "color": "#3366ff",
      "iconId": "claude",
      "supportsContextInjection": true
    }
  ]
}
FieldRequiredNotes
idyesAdditive for new ids only. Colliding with a built-in agent is a manifest error, and built-ins always shadow plugin entries. Cross-plugin conflicts resolve first-registered-wins.
nameyesDisplay label.
commandyesA bare binary name found on PATH, or a plugin-relative path starting with ./ for a launcher the plugin ships. No absolute paths, backslashes, or .. segments. Supports ${settings:id}.
argsnoUp to 20 default launch arguments, each up to 256 characters with no line breaks. Also supports ${settings:id}.
coloryesBrand color as a 6-digit hex.
iconIdyesA different namespace from panel and toolbar icons. Name one of Daintree's bundled agent brand marks by its id (claude, codex, …) or ship your own mark as a ./…svg path. A panel icon id like gauge is not an agent mark; an unrecognized value draws a generic terminal glyph.
supportsContextInjectionnoWhether copy-tree context injection targets this agent. Default false.
detectionnoWires the agent into working and waiting state. See below.
resumenoHow a restored or restarted pane reopens the conversation: "session-id" (args carrying the captured {sessionId}) or "project-scoped" (args that resume the latest session in the launch directory).
initialPromptFormnoHow the CLI takes a first prompt, interactively and headless, as args carrying {prompt} exactly once, as an argument of its own.
launchMcpno{ format }: the mechanism the CLI uses to merge extra MCP servers, so the agent can receive Daintree's own servers and plugin agent tools at launch as the project allows. Without it, a plugin agent gets neither.
permissionBypassArgsnoThe arguments that skip the CLI's permission prompts. They are added only to a launch whose Skip permission prompts setting resolves on, and the install dialog names every agent that declares them.
nativePaths, packagesnoWhere the CLI's own installer, npm, or PyPI puts it, for an install PATH does not reach. Discovery only checks for a launchable file; it never runs or installs anything.
executableNamesnoExecutable names that turn a plain terminal running the CLI into this agent. Defaults to a bare lowercase command; launchers such as npx or node are refused.

${settings:id} tokens in command and args resolve at spawn time against the plugin's user-scope setting of that id; project scope is never read. If the setting is unset the launch fails with a clear error rather than spawning the agent with a literal token or a silently blanked value, so a missing credential surfaces as a spawn error instead of an opaque auth failure inside the agent. Unlike MCP server tokens, these are not validated at parse time.

detection

Without a detection block a plugin agent runs as a plain named terminal whose working and waiting state Daintree does not track. Declare one and it joins the same agent-state machinery as a built-in. The block is strict, so a typo'd field is a loud manifest error rather than a silently ignored tuning knob.

FieldRequiredNotes
primaryPatternsyesNon-empty array of regex strings, each of which must compile, marking the agent as working. A detection block without it is rejected.
fallbackPatterns, bootCompletePatterns, promptPatterns, promptHintPatterns, completionPatternsnoRegex arrays for the corresponding detection tiers.
scanLineCount, promptScanLineCountnoLine-window bounds for the matcher, 1 to 1000.
debounceMs, promptFastPathMinQuietMsnoTimings in milliseconds, 0 to 600000.
primaryConfidence, fallbackConfidence, promptConfidence, completionConfidencenoConfidence weights in the range 0 to 1 for a matched tier.
titleStatePatternsno{ working, waiting } string arrays matched against the terminal title, up to 50 entries each.

Process tools

Teaches Daintree to recognize a CLI running inside a terminal pane, so the tab shows your icon instead of the generic terminal glyph. Detection normally runs off a fixed built-in list (npm, Vite, Docker and friends), and this is how a plugin that ships or wraps its own CLI gets the same treatment. Inert declarative data; no capability required.

"processTools": [
  { "command": "acme-cli", "iconId": "sparkles" },
  { "command": "acmec", "iconId": "sparkles" }
]

iconId takes a shared icon id or a ./…svg path to your own icon. An unrecognized id, including an agent brand id such as claude, is collapsed to the generic terminal glyph, so a plugin cannot borrow a built-in agent's mark.

command is a bare executable name, lowercase, starting with a letter or digit and otherwise limited to letters, digits, ., -, and _. Omit the extension: write acme, not acme.exe or acme.py, because detection strips launcher and script suffixes before matching, so a suffixed form would never fire and is rejected. Lowercase is enforced rather than normalized for the same reason.

Entries are additive for new commands only. Colliding with a built-in tool command or a built-in agent CLI is a manifest error, as is declaring the same command twice in one manifest. So are shells and launcher wrappers (sh, bash, sudo, env, xargs, timeout and the rest), because they name the process that runs a tool, so sudo vite would report your plugin instead of Vite. The package-manager exec subcommands exec, dlx, and x are rejected for the same reason. A collision with another plugin resolves first-registered-wins with a warning.

One entry per alias, each pointing at the same iconId. Plugin detections rank at the same tier as named built-in tools, so npm exec acme-cli reports your CLI rather than npm. Detections register at plugin load and are mirrored into the pty-host process where detection actually runs, surviving a pty-host restart; unloading or disabling the plugin removes them, and a terminal already running the command keeps its icon until the next detection pass reclassifies it.

Forge providers

Registers a forge backend (issues, pull or merge requests, reviews, CI roll-up, releases, and auth) for a platform that sits on top of git. See Code Forge.

Warning
Forge providers are effectively built-in only today. A provider's parseRemote and URL builders are synchronous and cannot cross the async MessagePort that user-installed plugins run behind, so registerForgeProvider is a no-op out of process. An installed plugin's provider is listed in settings as unavailable, cannot be picked, and fails forge calls with that reason. Project manifests reject the contribution outright. Daintree's own GitHub and GitLab plugins work because built-ins activate in-process.
"forgeProviders": [
  {
    "id": "gitea",
    "name": "Gitea",
    "matches": ["gitea.io", "gitea.example.com"],
    "capabilities": ["issues", "pulls", "required-checks"]
  }
]
FieldRequiredNotes
idyesMust match the descriptor id passed at runtime.
nameyesDisplay label in the forge settings.
matchesyesExact hostnames. The host extracts the hostname from the project's git remote (HTTPS, SSH, and SCP-form URLs all handled), lowercases it, and matches for exact string equality. No globs, no suffix matching. List every hostname your forge serves. First match wins. Must be empty for an issues-only provider.
matchesSettingRefnoA user-scoped string setting whose value (a hostname or https:// origin) is matched as one more matches entry, for a self-hosted instance.
rolesno["issues", "code"] by default. ["issues"] declares an issue tracker with no code hosting. A code-only provider is not supported.
referencePrefixesno{ issue?, pr? }: the characters the forge writes before an issue or pull request number, such as # or !.
kindno"network" for a provider that reaches a remote forge, "local" for one that serves a local or offline source. Display only.
capabilitiesnoInformational hints driving the "supports…" display only. Behavior gates on the runtime implementation, not on this list.
credentialFieldsno{ id, label, type, placeholder?, helpText? } entries driving the generated credential form.
settingsScopeRefnoA declared setting id used to group provider settings. A dangling reference is a manifest error.
viewRefsnoIds of views shown under this provider's section. Each must resolve to a declared view.
slotsnoRenderer view ids for settingsTab, icon, statsDropdown, bulkCreateWorktreeDialog, and issueSelector. Checked for shape only; an unresolved id renders a neutral fallback.

The manifest entry is read eagerly so the provider populates the settings UI and the remote-routing table before any plugin code runs; the implementation binds lazily in activate().

Cloud providers

Adds a cloud whose machines Daintree creates, starts, stops and deletes on the person's own account and uses as cloud machines: an EC2-style API, a VM service, any provider with an API. Each entry is registered as {pluginId}.{id} beside the built-in Boat, Agent 37, AWS, Google Cloud and DigitalOcean providers. Built-in plugins and installed plugins that run app-wide may declare them. A repository plugin, or an installed package with "instanceMode": "project", that declares one is refused, so a repository can never add something that creates machines on someone's account just by being opened. The full contract is the app repository's Implementing a Cloud Provider; when it and the types in shared/types/pluginCloudProvider.ts disagree, the types win.

"cloudProviders": [
  {
    "id": "ec2",
    "name": "EC2",
    "description": "Machines on your own AWS account.",
    "apiUrl": "https://ec2.amazonaws.com",
    "apiKeyUrl": "https://console.aws.amazon.com/iam/home#/security_credentials",
    "dashboardUrl": "https://console.aws.amazon.com/ec2/home",
    "docsUrl": "https://docs.aws.amazon.com/ec2/",
    "credentialFields": [
      { "id": "accessKeyId", "label": "Access key ID", "secret": false, "input": "single-line", "required": true },
      { "id": "secretAccessKey", "label": "Secret access key", "secret": true, "input": "single-line", "required": true }
    ],
    "capabilities": {
      "persistence": {
        "kept": "Its EBS volume",
        "lost": "Instance store and memory",
        "retentionDays": null,
        "saveRetryBilled": false,
        "stoppedComputeBilled": false,
        "stoppedStorageBilled": true
      },
      "typicalStartSeconds": 45,
      "lifetime": { "kind": "none" },
      "sshTrust": "confirm-on-first-connect",
      "transport": "direct",
      "tunnel": null,
      "provisioning": { "location": "required", "image": "required", "network": "optional", "sshKey": "at-create" },
      "deletion": true
    }
  }
]
FieldRequiredNotes
idyesLowercase letters and digits joined by single hyphens, at most 32 characters. Must match the id passed to host.registerCloudProvider in activate().
name, descriptionyesShown wherever the provider, its accounts and its machines are named.
apiUrlyesThe https origin (no path, query or fragment) of the provider's API. An account is tied to the origin it connected with, and Daintree releases its saved credentials to the plugin only while the provider still declares that origin. What the plugin does with them is up to its code.
apiKeyUrl, dashboardUrl, docsUrlyeshttps links opened in the system browser: where to create credentials, the provider's console, its docs.
credentialFieldsyes1 to 16 fields the connect form asks for, in order, each { id, label, secret, input, required, help? }. input is "single-line", "multi-line" or "key-file". Every value is kept encrypted with the OS keychain and never shown again.
capabilitiesyesWhat the provider can do, which every dialog about its machines is worded from. See below.
createReplayno"same-key" (the default) when create is idempotent on the request's idempotency key, so a create whose answer was lost may be sent again; "lookup-only" when a second send could make a second machine, so Daintree only ever looks for it.
CapabilitySays
persistenceWhat a stop keeps and loses, in words; the minimum number of days a stopped machine's data is kept (retentionDays, null for until deleted); whether a retried save is billed (saveRetryBilled); and what a stopped machine still bills: compute (stoppedComputeBilled, with an optional stoppedBilling sentence), only its disk (stoppedStorageBilled), or neither.
typicalStartSecondsHow long a start usually takes, or null.
lifetimenone (runs until stopped), fixed-at-create (a runtime limit that can't move while it runs, with canChangeWhileStopped), renewable (a deadline Daintree pushes back while the machine is in use; requires renewLifetime) or idle-sleep (the provider sleeps it after idleSeconds, null when unknown).
sshTrust, transport, tunnelHow the machine's ssh server is reached (direct, or provider-command: your provider's own CLI as ssh's ProxyCommand, declared in tunnel as a bare command name, plain arguments or ssh's %h, %p, %r, %n, and an https installUrl) and where trust in its host key comes from: pinned-from-api, confirm-on-first-connect or api-or-confirm (both direct only), or provider-tunnel.
provisioningWhether a create takes a location, image and network (none, optional or required), and whether the SSH key goes with the create (sshKey: "at-create", answered by sshAccess) or is put on afterwards ("after-create", answered by authorizeSsh).
deletionWhether machines can be deleted from Daintree.

The worker binds the implementation in activate() with host.registerCloudProvider({ id }, impl): checkCredentials, validate, catalog, list, inspect, create, start, stop, rename, delete, and sshAccess or authorizeSsh to match provisioning.sshKey. Every call except checkCredentials receives the account's credentials, its billing scope and the declared apiUrl, for that one call; keep no state between calls. Each call has 30 seconds, activation included, and an abort signal to honor. Daintree, not the plugin, decides when a machine is idle and when to apply its own idle stop; a provider may still sleep a machine by itself. Throw an Error with a code such as credential-invalid, permission, billing, capacity or not-found to say what went wrong; a crash or a missed deadline reads as provider-unreachable on that account.

At most 8 providers per plugin. No capability token is needed, but the person consents to the plugin before its first account is connected, and again after an update that changes what its providers ask for or do; until then its accounts are paused. See Cloud provider consent and, for what the person sees, Providers From Plugins.

File decorations

Registers a provider that decorates file rows with status badges, colors, and tooltips. The manifest declares which scopes the provider answers for, so the renderer can route decoration pulls before the plugin's code has run.

"fileDecorationProviders": [
  { "id": "worktree-diff-review", "scopes": ["worktree-diff:*"] }
]

id must match the id passed when the provider binds at runtime; scopes is a non-empty list of patterns, an exact scope or a prefix ending in *. The optional forgeProvider names one of the plugin's own forge providers, so the decorator is only started and asked for projects whose forge resolves to it. There are two host-routed scopes, and keeping them distinct is the point:

ScopeSurfaceTypical use
worktree-diff:<worktreePath>Review Hub changed-file rows: base-branch diff and linked PR.Badging PR review state, as the built-in GitHub plugin does.
worktree-files:<worktreePath>The local file-change list on the worktree card.Local-only signals: lint status, leaked secrets, format drift. No PR or remote required.

A provider registered for worktree-diff:* is not invoked on worktree-files:* and vice versa, so PR-review badges never leak onto the plain change list. The paths the host passes, and that your provider keys its returned map by, are the changed-file paths as the surface renders them.

Two providers declaring the same exact scope string merge first-writer-wins per field in load order, so the second one's badge for a shared path can be dropped; the host logs a warning naming both plugins so the collision is detectable. A broad provider coexisting with a narrow one (worktree-files:* alongside worktree-files:/some/path) is intentional and not warned about.

A provider that takes longer than 3000 ms to answer a pull is skipped and logged, so one slow provider cannot stall the file list. From your subscriptions and timers, call host.invalidateFileDecorations(scope, paths?) to tell any renderer showing that scope to re-pull.

File editors

Declares an editor the file panel offers for matching files. An entry names exactly one backing:

  • View-backed, open to every plugin: view names one of the plugin's own location: "fileEditor" views, and mode says what it fills. "edit" fills the file panel's writable Edit mode; "view" fills Rendered for a type the host cannot render itself, as the built-in CSV viewer does.
  • Slot-backed, built-in plugins only: slot names a view compiled into the app's bundle, which no other plugin's code reaches. The built-in Markdown editor is the one contributor.
"views": [
  { "id": "records-editor", "componentPath": "dist/editor.js", "location": "fileEditor" }
],
"fileEditors": [
  { "id": "records", "view": "records-editor", "mode": "edit", "extensions": ["json"] }
]

An editor matches by extensions (bare lowercase suffixes), and a project plugin may also match project-relative paths globs and mark an Edit editor default for them. maxBytes caps the file size it accepts, 2 MiB by default and 64 MiB at most. Otherwise the user's remembered pick wins, then Daintree's own editor where it has one: a plugin editor adds a choice behind Edit with… or View with…, the pick is remembered per project and file type, and Source is always one click away. The view receives a host-owned document: in Edit mode it saves only against the revision it read and keeps the unsaved draft; in View mode it is read-only. At most 10 per plugin.

Element Picker providers

contributes.elementPickerProviders teaches the dev preview's Element Picker about a framework Daintree does not ship an extractor for. A provider declares what to look for on a page and a packaged script that reads it; the host loads the script only when the picker is on and the declared markers match. Requires the preview:inspect capability.

"capabilities": ["preview:inspect"],
"contributes": {
  "elementPickerProviders": [
    {
      "id": "lit",
      "name": "Lit",
      "detection": [
        { "kind": "global", "name": "litElementVersions", "match": "exact" },
        { "kind": "tag", "name": "acme-", "match": "prefix" }
      ],
      "guestEntry": "dist/picker/lit.js"
    }
  ]
}
  • Detection is data. Up to 16 rules, each naming a global, an expando key on a node, an attribute, or a tag, compared exact or by prefix. The host compares names only and never runs plugin code to decide.
  • The id is qualified as {plugin name}.{id} and cannot be a core framework name such as react or svelte.
  • guestEntry is a packaged, plugin-relative browser script of at most 256 KiB. It never starts the plugin's worker; a missing or failing script leaves DOM picking as it was.
  • resolverEntry is an optional module that turns the extractor's source candidates into checked file and line results, and requires fs:project-read.

This replaces the retired previewTools and guestAdapters contributions, which let only built-in plugins add a preview toolbar tool. At most 20 per plugin.

What is deliberately not a contribution point

  • Model-provider implementations. Registering a launchable CLI does not add a model provider to Daintree's assistant.
  • Agent lifecycle interception. Plugins can observe the supported agent-state API; they do not gain a hook that intercepts an agent CLI's tool calls. A plugin that wants agents to route work through it serves its own agent MCP tools.
  • Subagents. Daintree spawns fresh agents natively. Compose them with skills and MCP rather than a subagent contribution.
  • Status bar items, tree views, editor decorations. Daintree is not an editor; these surfaces do not map onto what it renders.

Exact field definitions and limits live in the manifest schema, its cross-field validators, and the public types. The contribution-consumer tests trace declarations to their runtime consumers. The app's own contribution points guide goes deeper on each. These links are pinned to the November 20, 2026 revision this page was checked against.