Outirl Plugin SDK

@outirl/plugin-sdk connects your panel plugin to its Outirl workspace. Build panels that read project context, explore Git history, display architecture, and run the script actions available in Outirl.

The package ships ESM JavaScript and TypeScript declarations with no runtime dependencies. The same compiled SDK is used in development and production.

Install

npm install @outirl/plugin-sdk

Bundle the SDK with your plugin using a browser bundler such as Vite. Call connectOutirlPlugin() inside the plugin iframe once it mounts. The connection requires an Outirl host; importing the package alone does not open one.

import { connectOutirlPlugin, OutirlPluginError } from "@outirl/plugin-sdk";

const outirl = await connectOutirlPlugin();
const context = await outirl.context();
const unsubscribe = outirl.subscribeContext((next) => {
  console.log(next.project?.name);
});

try {
  const actions = await outirl.scripts.actions();
  console.log(context.project?.name, actions);
} catch (error) {
  if (error instanceof OutirlPluginError) console.error(error.code);
  else throw error;
}

// When unmounting the plugin:
unsubscribe();
outirl.dispose();

Plugin manifest

Your plugin must declare the permissions it needs. For example, a panel that reads the active project and lists script actions can use:

import {
  PANEL_PLUGIN_MANIFEST_VERSION,
  PANEL_PLUGIN_SDK_VERSION,
  type PanelPluginManifestV1,
} from "@outirl/plugin-sdk";

export const manifest = {
  manifestVersion: PANEL_PLUGIN_MANIFEST_VERSION,
  id: "project-actions",
  name: "Project Actions",
  description: "Script actions for the current project",
  version: "0.1.0",
  sdkVersion: PANEL_PLUGIN_SDK_VERSION,
  entry: "index.html",
  context: { project: true },
  permissions: ["context.project.read", "script.read"],
} satisfies PanelPluginManifestV1;

Save the manifest as .outirl/plugin.json and set entry to the HTML entry in your built plugin bundle. Outirl's plugin creation flow generates a project with the SDK embedded locally so it can build without fetching this package.

Capabilities

| Task | API | Manifest permission | | --- | --- | --- | | Read workspace context | context(), subscribeContext() | context.host.read, context.project.read, or context.session.read | | Explore Git history | git(), gitCommit() | git.read | | Read or refresh architecture | architecture(), refreshArchitecture() | architecture.read, architecture.refresh | | Persist plugin data | readStorage(), writeStorage() | storage.read_write | | Navigate in Outirl | navigate() | navigation.open | | Refresh or close the panel | refresh(), closePanel() | panel.refresh, panel.close | | Create or open a workspace session | sessions.create(), openSession() | session.create, session.open | | List or run script actions | scripts.actions(), scripts.run() | script.read, script.run |

The host grants capabilities from the plugin manifest; permissions lists the current grants. Calls may fail if permission is missing, context changes, or confirmation is declined. Plugin capabilities do not include arbitrary shell, filesystem, clipboard or network access.

Each connection and handshake stage times out after 15 seconds. Most requests time out after 30 seconds; architecture refresh allows 135 seconds. Dispose the connection on unmount to reject pending requests and release listeners.

Types and compatibility

Exported types include OutirlPluginApi, PanelPluginManifestV1, PanelPluginPublicContext, PluginScriptRunOptions, GitLogPage and ArchitectureResponse. Architecture describes the project's file tree and statistics returned by the host.

Use PANEL_PLUGIN_SDK_VERSION for the manifest's sdkVersion, as shown above. This host compatibility version (2.0.0) is independent of the npm package version. The SDK handles bridge messages and connection identifiers for you.

License

MIT. See LICENSE.