Extensions

An extension is a folder with a .spirit/extension.json — the Spirit manifest dump — next to a pure-npm package.json. Spirit installs extensions per user and per host, not under the workspace .spirit/ directory, and scopes each install by the marketplace it came from: the install identity is (source id, name).

That is different from Skills (SKILL.md folders), MCP (external servers), and Hooks (hooks.json scripts). contributes.cli.hooks styles CLI TUI slots. It is not hooks.json. An extension can still bundle those same files when it declares mcp, hooks, skills, or rules.

Each installed extension has an enable switch. Disable or uninstall it to stop its contributions. Turning the extension on is consent to run the MCP servers, agent hooks, skills, and rules it declared.

Create an extension

npm create @spiritagent/extension

npx @spiritagent/extension-toolkit check ./my-extension

The manifest

The manifest object is the extension's runtime declaration: which hosts it supports, when it activates, and what it contributes. In a marketplace entry, the manifest is endorsed by the marketplace operator; in a ZIP package, it is self-declared and gated by the review confirmation.

Capabilities

desktop-ui / cli-ui / mcp / hooks / skills / rules and the matching contributes entry must both be present or both be absent.

Activation events

The host calls activate when the extension lists the event and has a readable main.

contributes.tools

The model does not see name as-is. The host builds an invocation name such as extension__{id}__{tool}__{hash}.

contributes.desktop

Requires desktop-ui.

Default export: export default function View({ params, close }). close(result) finishes the view. The host injects React and @spirit/desktop-ui.

contributes.cli

Requires cli-ui. hooks is an object with path, not an inline array:

{
  "hooks": { "path": "cli-hooks.json" }
}

The file must be { "hooks": [ ... ] }.

Slots: message.user, message.assistant, message.tool, assistant.thinking, input.frame, bottom_form, bottom_form.section, slash_suggestions, approval.panel, questions.panel.

Token roles: default, primary, secondary, muted, accent, success, warning, danger.

{
  "hooks": [
    {
      "slot": "input.frame",
      "variant": "accented",
      "tokens": { "border": "accent" },
      "prefix": "[",
      "suffix": "]"
    }
  ]
}

Bundled MCP, hooks, skills, and rules

Requires the matching capability. contributes.mcp, contributes.hooks, contributes.skills, and contributes.rules are true or {}. Paths are conventional; custom paths are not allowed.

Declared but missing or invalid files fail install. Files in the package that are not declared are ignored and never loaded.

Relative command and cwd values resolve against the extension root. If an MCP stdio server omits cwd, it defaults to the extension root. PATH-only commands are unchanged.

These contributions overlay into the agent session when the extension is enabled. They do not appear in Settings → MCPs | Hooks | Skills | Rules. On a name conflict, workspace wins, then user, then extension.

During tools/call, a bundled MCP server may send a JSON-RPC request spirit/ui/open with { viewId, params } when the client advertised experimental["spirit/ui"]. Spirit only opens a view declared by the same extension in contributes.desktop.views. User and workspace MCP servers are rejected. The Dialog stays open while that tools/call is in flight; close(result) returns on the same request. Hosts without a window respond { "kind": "unavailable", "reason": "host-has-no-ui" } — the tool should degrade.

settingsSchema

Values are string, number, boolean, or null. null clears a non-required setting.

secretSlots

Desktop stores secrets in the OS keyring. On the CLI daemon path, secrets.set / secrets.delete may be unavailable.

activate

main is loaded with dynamic import. Export one of:

• export function activate(ctx) { ... }
• export default function activate(ctx) { ... }
• export default { activate }

ctx

Return value

Return an object, or export the same fields from the module.

Tool handler ctx

A string result is passed through. Other values are JSON.stringify(value, null, 2). undefined becomes "".

Desktop host.showMessageBox

export function activate(ctx) {
  return {
    systemPrompt: "Use lookup_item when the user asks for an item by id.",
    async invokeTool({ toolName, arguments: args, settings, secrets }) {
      if (toolName !== "lookup_item") {
        throw new Error(`Unknown tool: ${toolName}`);
      }
      const region = await settings.get("region");
      const token = await secrets.get("api_token");
      return { id: args.id, region, hasToken: Boolean(token) };
    },
    dispose() {
      ctx.log("example-extension disposed");
    },
  };
}

Distribute as a ZIP

Pack an extension directory into the shareable ZIP format (content plus .spirit/extension.json):

npx @spiritagent/extension-toolkit pack ./my-extension

The command validates the package first and writes <name>-<version>.zip to the current directory. Users import the ZIP from the Extensions page or with spirit extension import; it lands in their Personal marketplace. See Extensions.

To list the extension in a marketplace instead, see Publish to a marketplace.

Run a marketplace

A marketplace is a servable directory with a .spirit/marketplace.json index: a Git repository, a static site, or a local directory. Users add it with spirit extension marketplace add <url|path> or from the Desktop Extensions page, then browse and install its entries.

Local marketplaces

Any local directory with a .spirit/marketplace.json works as a marketplace — add it with spirit extension marketplace add <path> or Desktop Add from Disk. Local marketplaces are read in place and need no CI, which makes them the development loop for extension authors: edit, reinstall, repeat.

Publish to a marketplace

extension-toolkit publish merges an extension's .spirit/extension.json into a marketplace's .spirit/marketplace.json and copies the content the entry's source needs:

npx @spiritagent/extension-toolkit publish ./my-extension ./my-marketplace

• The first argument is the extension directory; the second is the marketplace root — any local directory with a .spirit/marketplace.json: a template-repository clone, the Personal marketplace at {spiritDataDir}/marketplaces/personal, and so on.
• --source local (default): copy the full package into the marketplace's extensions/<name>/ — including .spirit/extension.json, excluding node_modules and .git — and point the entry's source at it.
• --source npm: pin name@version from the extension's package.json as the entry's npm source; only the declared icon is copied into extensions/<name>/ (marketplaces self-host icons). Publishing the npm package itself stays with your npm CLI.
• --dry-run: print the entry and the planned actions without writing anything.
• Merge rules: a same-name entry is replaced in place, otherwise the entry is appended. New entries and version changes fall back to reviewStatus: "unverified"; republishing the same version keeps it. Curation fields such as featured always keep the marketplace's values.
• The same validation as check runs first; on failure nothing is written.