Plugin reference

For Isee v0.8 beta. Return to the v0.8 quickstart.

Migrating an existing plugin? Follow the standalone runtime-entry migration guide.

Local plugins are directory sources installed into one Isee daemon. A plugin can contribute:

React Native surfaces and sidebar items to Isee clients;
workspace and agent panels opened as workspace tabs;
global, workspace, and agent actions in the Command Center;
slash commands in the message composer;
transformed and daemon-pushed agent timeline rows;
light and dark themes in Settings → Appearance;
schema-validated RPC handlers running beside the daemon;
normal Isee operations through the TypeScript SDK;
searchable external resources in the message composer.

Plugin code is trusted and unsandboxed. Client surfaces run in the Isee app. Backend contributions run in a subprocess with access to the daemon machine, including its files, processes, credentials, and network.

Project files

paseo plugin init /absolute/path/to/my-plugin creates:

my-plugin/
  paseo-plugin.json
  index.client.tsx
  index.server.ts
  client/greeting.tsx
  server/greeting.ts
  shared/greeting.ts
  package.json
  tsconfig.json

The required root manifest is paseo-plugin.json. It contains the default plugin ID and supported Isee versions:

{ "id": "my-plugin", "requirements": { "paseo": ">=0.8.0" } }

Requirements

requirements is an optional object. Its currently supported key, paseo, accepts an npm semver range. An omitted requirements.paseo means <0.8.0: the plugin predates the first breaking plugin release. Isee 0.8 and later reject it with a link to the migration guide. Empty strings, invalid ranges, and unknown manifest requirement keys are rejected.

Range	Compatible releases
`>=0.8.0`	0.8.0 and later releases, including prereleases and future breaking releases
`^0.8.0`	0.8.x releases, including prereleases
`>=0.8.3 <0.9.0`	0.8.3 through the last 0.8 patch, including prereleases

Prerelease Isee versions also satisfy a range their stable core (major.minor.patch) satisfies, so 0.8.0-beta.1 satisfies >=0.8.0 but not <0.8.0.

paseo plugin init writes >= followed by the current CLI version and pins the matching SDK for typechecking. Raise the minimum when adopting a newer API. Add an upper bound when a later release is incompatible; a minimum alone does not promise protection from future breaking changes.

The daemon checks its version before installing, running Git build commands, or loading a plugin, and checks again on startup, enable, and reload. A rejected Git update keeps the installed revision. Each connected app checks its own version before evaluating client code and shows incompatibility in Settings → Plugins. A compatible daemon does not make an older app compatible. A plugin with no client entry does not require the connected app to match.

For example: Plugin "review" requires Isee >=0.8.0. Your daemon is 0.7.2. Use a compatible plugin revision or update the named runtime. Releases before 0.8 do not understand this manifest field and cannot show this new diagnostic.

Runtime entries

Entry	Runtime	Receives	Required
`index.client.tsx`	Isee app, per client	`PluginClientContext`	When the plugin has any UI, callback, theme, or attachment source
`index.server.ts`	Daemon subprocess	`PluginServerContext`	When the plugin contributes handlers, hooks, settings persistence, or providers

At least one entry is required; both accept .ts or .tsx. A directory that still has only the old index.ts fails to load and points at the migration guide.

Plugin, surface, sidebar-item, workspace-panel, Command Center item, attachment-source, and slash-command IDs start with a lowercase letter and contain lowercase letters, numbers, or hyphens.

The generated package.json installs @getpaseo/plugin and the other host modules as development dependencies for local typechecking and tests. Isee supplies their runtime instances. Consumers do not install them when adding the plugin.

Every other module lives in one of three directories. Nesting inside them is fine; a module at the plugin root is a compile error.

Directory	Compiled into	Use it for
`client/`	App bundle only	React, React Native, hooks, styles, surfaces, panels, and callbacks.
`server/`	Daemon bundle only	Node APIs, local resources, credentials, and RPC handlers.
`shared/`	Both	Zod RPC contracts and plain values imported by both runtimes.

Runtime modules

Isee builds each bundle from its matching entry. An import from client/ into the daemon bundle, from server/ into the app bundle, or of a Node module anywhere in the app bundle is a compile error. Server imports of React, React Native, or client SDK entries also fail. Shared code imports only shared code: no Node, React, runtime-specific SDK entries, or runtime-specific types.

The SDK root (@getpaseo/plugin) contains shared data, schemas, and runtime-neutral helpers only. Import client contexts and hooks from /client, server contexts and lifecycle contracts from /server, and UI from /client/react-native or /client/ui. These rules include type imports and transitive dependencies. /client/host is private to the app host; plugins cannot import it.

Client runtime

Isee provides these modules to client code:

Module	Use it for
`@getpaseo/plugin`	Shared data, `defineRpc`, `defineSettings`, `defineAttachmentSource`, `RpcInput`, and `RpcOutput`
`@getpaseo/plugin/client/ui`	Named, composable settings components
`@getpaseo/plugin/client/react-native`	Isee UI components and UI hooks
`@getpaseo/plugin/client`	Client contribution contexts, `useIsee`, `useRpc`, `useSettings`, and data hooks
`@tanstack/react-query`	Request state and caching
`react`	Components and hooks
`react/jsx-runtime`	Compiled JSX
`react-native`	Cross-platform UI
`zod`	Shared schemas

The host owns its paired React and renderer versions. The SDK's React peer range permits patch versions for tooling and Node consumers; it does not change the app's pinned React version or guarantee compatibility with another host's renderer.

These exact module specifiers use the host's runtime instances. A client bundle that requests another host module fails with Module "<name>" is not available in plugin client code.

Do not import lucide-react-native, react-native-svg, or DOM libraries. Set contribution icon fields to a Lucide icon name; Isee validates the name and renders the icon.

Cross-platform rules

Client code runs on iOS, Android, and in browsers through React Native Web. A component that works in your browser and crashes on a phone is the most common plugin bug. The rules:

Do	Do not
`View`, `Text`, `Pressable`, `ScrollView`, `TextInput` from `react-native`	`<div>`, `<span>`, `<button>`, or any HTML element
`style` objects built from `theme.colors` and `layout.compact`	`className`, CSS strings, or hardcoded colors
`onPress`	`onClick`, `onMouseEnter`, or other DOM handlers
`Linking`, `Clipboard`-style React Native APIs	`window`, `document`, `localStorage`, `navigator`, `location` in components

The scaffold's tsconfig.json omits the DOM library, so document and window are type errors everywhere by default. The one place browser APIs are allowed is client/web.ts. It declares the narrow shape of each global it uses, gates every export on Platform.OS, and gives native the alternative:

client/web.ts:

import { Linking, Platform } from "react-native";

// This plugin typechecks without the DOM library. Declare only what this module uses.
declare const window: { open(url: string, target: string, features: string): unknown };

export async function openExternal(url: string): Promise<void> {
  if (Platform.OS === "web") {
    window.open(url, "_blank", "noopener,noreferrer");
    return;
  }
  await Linking.openURL(url);
}

Do not add /// <reference lib="dom" /> or "DOM" to lib; either one turns DOM types back on for the whole project and hides the next mistake. Components import openExternal and never touch window themselves. layout.platform on surface and panel props carries the same value as Platform.OS for rendering decisions.

Use the settings API for typed host-scoped persistence across clients. Use openSettings, openSurface, and openPanel for your own registered contributions.

Server runtime

Isee provides @getpaseo/plugin, @getpaseo/plugin/server, @getpaseo/plugin/server/provider, @getpaseo/plugin/server/acp, and zod to server code. Backend contributions run in a daemon subprocess with Node access to the host machine. Keep filesystem, process, credential, and other machine-local work under server/. A plugin without index.server.ts starts no subprocess.

Providers

Follow Build a provider plugin for direct and ACP implementations, session lifecycle, composer settings, timeline renderers, testing, and distribution.

Call server.registerProvider() with a ProviderRegistration from @getpaseo/plugin/server/provider. Its connection accepts inputs with send() and emits complete state snapshots through onEvent(). send() reports acceptance only; prompt disposition, turns, configuration, persistence, permissions, and failures are events.

Use the single session.prompt input for messages, structured commands, steering, and command side effects. Repeat clientMessageId on the live user timeline item and publish exactly one matching session.prompt_result. Publish provider-created children as sessions with parentSessionId.

Provider settings are toggle/select descriptors that Isee renders in the composer. Keep provider-private JSON under providerOptions. Host tools arrive as MCP servers in the complete session config.

Isee refreshes an agent by closing its current provider session and opening it with current configuration and persistence. Providers re-read external state during session.open.

Use runAcpProvider() from @getpaseo/plugin/server/acp to adapt a command-backed ACP. Add transformer hooks only for a vendor's discovery, configuration, notification, or tool-call differences.

ProviderRegistration.icon is a file path relative to the plugin directory, such as icon.svg. It must resolve inside that directory to a regular SVG file no larger than 64 KiB. The SVG must be self-contained: scripts, styles, foreignObject, event-handler attributes, JavaScript URLs, and external href or xlink:href references are rejected. Fragment references such as #mark are allowed. Isee reads and sanitizes the file when the plugin starts; the string is never an inline SVG or URL.

Entry point and cleanup

Each present entry default-exports one contribution function and returns cleanup. Client entries receive PluginClientContext; server entries receive PluginServerContext. Client registration methods return idempotent removers, except header buttons and composer pills, which return { update, remove } handles. The entry cleanup runs before Isee removes remaining registrations.

import type { PluginClientContext } from "@getpaseo/plugin/client";
import { Main } from "./client/main";

export default function contribute(client: PluginClientContext) {
  client.addSurface("main", Main);
  return () => {};
}

Cleanup can be async. Release timers, watchers, sockets, and other resources created by the plugin. Isee also removes registrations, unmounts surfaces, rejects pending RPCs, closes the plugin's daemon session, and stops its subprocess on reload, disable, removal, disconnect, or daemon shutdown.

Lifecycle hooks

In index.server.ts:

import type { PluginServerContext } from "@getpaseo/plugin/server";

export default function contribute(server: PluginServerContext) {
  server.on("agent.turn_ended", (event) => {
    console.log(event.agent.id, event.outcome);
  });

  return () => {};
}

Register	Callback receives	Return
`server.on(name, callback)`	`(event, { paseo, signal })`	`void` or `Promise<void>`
`server.before(name, callback)`	`({ request }, { paseo, signal })`	Modified request, or `undefined` to keep it; async supported

Hooks run on the daemon while the plugin is enabled, even with no app connected.

Change configuration and inject an MCP server

Add this callback inside contribute(server). Replace the placeholder URL with your MCP endpoint.

server.before("agent.create", ({ request }) => {
  if (request.config.provider !== "codex") {
    return request;
  }

  return {
    ...request,
    config: {
      ...request.config,
      providerOptions: {
        ...request.config.providerOptions,
        sandbox_mode: "workspace-write",
        approval_policy: "on-request",
      },
      mcpServers: {
        ...request.config.mcpServers,
        company: {
          type: "http",
          url: "https://tools.example.com/mcp",
        },
      },
    },
  };
});

Input	Result
`providerOptions.sandbox_mode: "read-only"`	`"workspace-write"`
`providerOptions.web_search: "disabled"`	Preserved by the spread
Existing `mcpServers.search`	Preserved by the spread
Existing `mcpServers.company`	Replaced with the entry above

The selected provider validates providerOptions and must support the configured MCP servers. Explicit Codex sandbox and approval options override its mode presets.

Inject environment variables on every session opening

server.before("agent.session_open", ({ request }) => {
  return {
    ...request,
    env: {
      ...request.env,
      COMPANY_ENV: "development",
    },
  };
});

This runs on create, resume, refresh, and import. To inject only on creation, set env in an agent.create callback instead.

Choose workspace isolation

server.before("workspace.create", ({ request }) => {
  if (request.source.kind !== "directory") {
    return request;
  }

  return {
    ...request,
    source: {
      kind: "worktree",
      cwd: request.source.path,
      action: "branch-off",
    },
  };
});

Result: an explicit directory creation request becomes a worktree request. Existing workspaces and directory lookup/import operations are unaffected.

Send a follow-up when a turn ends

Copy server/inspect.ts into your plugin. The helper imports types from @getpaseo/protocol/agent-types; add @getpaseo/protocol at the same version as your plugin SDK to your development dependencies and install them before loading the plugin. latestOutputText joins text chunks after the latest user message.

import type { PluginServerContext } from "@getpaseo/plugin/server";
import { latestOutputText } from "./server/inspect";

export default function contribute(server: PluginServerContext) {
  server.on("agent.turn_ended", async (event, context) => {
    if (event.outcome.kind === "canceled") {
      return;
    }

    const text = latestOutputText(event.timeline);
    if (/out of credits/i.test(text)) {
      await context.paseo.agents.ref(event.agent.id).send("Try again.");
    }
  });

  return () => {};
}

Turn ends: "out of credits"
  → plugin sends "Try again."
  → a new turn starts

This sends a new message with the existing SDK. Persistent matches keep sending follow-ups; add limits or delays in your plugin when needed. Attachments and tool effects are not replayed.

Answer a permission request

Using shellCommand from the same helper file:

import type { PluginServerContext } from "@getpaseo/plugin/server";
import { shellCommand } from "./server/inspect";

export default function contribute(server: PluginServerContext) {
  server.on("agent.permission_requested", async (event, context) => {
    const command = shellCommand(event.request);
    if (command === null) {
      return;
    }

    const agent = context.paseo.agents.ref(event.agent.id);
    if (/\brm\s+-rf\b/.test(command)) {
      await agent.respondToPermission({
        requestId: event.request.id,
        response: { behavior: "deny", message: "Recursive deletion is blocked." },
      });
      return;
    }

    if (command.trim() === "git status") {
      await agent.respondToPermission({
        requestId: event.request.id,
        response: { behavior: "allow" },
      });
    }
  });

  return () => {};
}

Request	Result
`rm -rf build`	Declined
`git status`	Approved
Other command or request	Left pending for the user
Already-resolved request	SDK response fails

The regex is an example policy, not a shell parser. Permission requests can also be questions, plans, and mode changes; requesting permission does not end the turn.

Events

Name	Event fields	Trigger
`agent.created`	`agent`	Ordinary creation finishes; excludes import/resume
`agent.turn_started`	`agent`, `turnId`	Live turn starts
`agent.turn_ended`	`agent`, `turnId`, `outcome`, `timeline`	Live turn completes, fails, or is canceled
`agent.permission_requested`	`agent`, `request`	Permission or question becomes pending
`agent.permission_resolved`	`agent`, `requestId`, `resolution`	Pending request is answered or cleared
`agent.archived`	`agent`, `archivedAt`	Archive state is saved
`workspace.created`	`workspace`	Record created; directory available
`workspace.archived`	`workspace`	Archive state is saved

Agent events exclude internal utility agents. Archive events can precede runtime/worktree cleanup; workspace.created is not a setup barrier before agent startup.

Shared payload shapes (@getpaseo/plugin/server):

interface PluginHookAgent {
  id: string;
  workspaceId: string | null;
  parentAgentId: string | null;
  provider: string;
  cwd: string;
  title: string | null;
}

interface PluginHookWorkspace {
  id: string;
  projectId: string;
  cwd: string;
  name: string | null;
  archivedAt: string | null;
}

type PluginTurnOutcome =
  | { kind: "completed" }
  | { kind: "failed"; error: { message: string; code?: string } }
  | { kind: "canceled"; reason: string };

Field	Shape / meaning
`turnId`	Provider-reported `string` or `null`; can repeat after a session reopens
`timeline`	`readonly AgentTimelineItem[]`; complete snapshot including earlier conversation; text may span items
`request`	SDK `AgentPermissionRequest`; `kind` is `tool`, `plan`, `question`, `mode`, or `other`
`resolution`	SDK `AgentPermissionResponse`
`archivedAt`	Timestamp string

Before hooks

Name	Request fields	Editable
`agent.create`	`config`, optional `env`	Public agent config except `cwd`; `env`
`agent.session_open`	`agentId`, `workspaceId`, `provider`, `cwd`, `reason`, `purpose`, `env`	Only `env`
`workspace.create`	`source`, optional `title`, `firstAgentContext`	Entire explicit creation request

agent.create.config uses AgentSessionConfig:

Fields	Constraint
`provider`, `model`	Separate fields; changing provider may require changing model/mode/options
`modeId`, `thinkingOptionId`, `featureValues`	Provider-specific selections
`title`, `systemPrompt`	Agent configuration
`providerOptions`	Provider-specific validated options
`mcpServers`, `toolPolicy`	MCP configuration and exact-tool preapprovals
`cwd`	Cannot change
`internal`	Daemon-owned; cannot change through this hook

agent.session_open request example:

{
  "agentId": "agent-123",
  "workspaceId": "workspace-456",
  "provider": "codex",
  "cwd": "/projects/shop",
  "reason": "resume",
  "purpose": "interactive",
  "env": { "COMPANY_ENV": "development" }
}

Field	Values
`workspaceId`	String or `null`
`reason`	`create`, `resume`, `refresh`, `import`
`purpose`	`interactive`, `history`
`env`	Launch override map; excludes the daemon's inherited environment. Replace the map to add, replace, or remove overrides.

Ordering and returned values

Creation request
  → agent.create hooks (plugin-ID order; registration order within each plugin)
  → resolve defaults and validate provider configuration
  → derive launch configuration with Isee runtime tools and daemon prompt
  → agent.session_open hooks (same ordering; env only)
  → set PASEO_AGENT_ID and PASEO_AGENT_CWD
  → open provider session and save agent configuration

Callback returns	Next callback receives
`{ ...request, env: { ...request.env, REGION: "eu" } }`	Prior request with `REGION` added/replaced
`{ ...request, env: { REGION: "eu" } }`	Prior request with the entire override map replaced
`undefined`	Unchanged request
Throws or returns invalid data	Operation fails; later callbacks do not run

No automatic deep merge. Later callbacks can overwrite earlier values. Agent configuration is saved; environment overrides are not persisted with it.

Context and cleanup

Contract	Behavior
`context.paseo`	Existing SDK connected to this daemon
`context.signal`	Aborted on invocation timeout or plugin stop; pass to external requests
Input data	Detached snapshot; change state through returned requests or SDK commands
Registration result	Idempotent remover, e.g. `const remove = server.on(...); remove();`
Reload, disable, removal, shutdown	Remaining registrations removed
Unknown hook name	Registration fails
Hook timeout	30 seconds; aborts the signal. A before hook fails the pending operation; an event handler logs an error.
Event-handler error	Logged against plugin; original operation continues
Event delivery	Live, best effort; no replay, persistence, or automatic retry
Event concurrency	Different events may overlap; callback completion order is not guaranteed

Complete examples

Plugin	Includes
lifecycle-logger	All eleven hooks; JSON logs with environment values redacted
lifecycle-actions	Follow-ups, permissions, environment, provider switching, worktree selection
agent-configuration	MCP injection and Codex sandbox/approval options

Read logger output with paseo plugin logs lifecycle-logger or the host's daemon.log.

client/main.tsx:

import type { PluginSurfaceProps } from "@getpaseo/plugin/client";
import { useMemo } from "react";
import { Text, View } from "react-native";

export function Main({ theme, host, layout }: PluginSurfaceProps) {
  const styles = useMemo(
    () => ({
      screen: {
        flex: 1,
        padding: layout.compact ? 16 : 24,
        backgroundColor: theme.colors.surface0,
      },
      title: { color: theme.colors.foreground },
      detail: { color: theme.colors.foregroundMuted },
    }),
    [theme, layout.compact],
  );
  return (
    <View style={styles.screen}>
      <Text style={styles.title}>{host.label}</Text>
      <Text style={styles.detail}>{layout.platform}</Text>
    </View>
  );
}

index.client.tsx:

import type { PluginClientContext } from "@getpaseo/plugin/client";
import { Main } from "./client/main";

export default function contribute(client: PluginClientContext) {
  client.addSurface("main", Main);
  client.addSidebarItem({
    id: "main",
    title: "My plugin",
    icon: "Blocks",
    surface: "main",
  });
  return () => {};
}

PluginSurfaceProps contains:

Field	Meaning
`theme`	Typed `PluginTheme` color tokens for the active Isee theme.
`host`	Selected host `id` and display `label`.
`layout`	`compact` and the `ios`, `android`, or `web` platform.
`navigation`	Optional client navigation. `openAgent({ agentId })` and `openWorkspace({ workspaceId })` open targets on the selected host.

Isee owns the route, header, close action, host picker, error boundary, and query client. The plugin owns the surface body.

Host UI

Import Isee-owned UI from @getpaseo/plugin/client/react-native in client code. This example opens a controlled modal, renders a host icon, and confirms the action with a toast:

import type { PluginSurfaceProps } from "@getpaseo/plugin/client";
import { Icon, Modal, useToast } from "@getpaseo/plugin/client/react-native";
import { useState } from "react";
import { Pressable, Text, View } from "react-native";

export function IssueActions({ theme }: PluginSurfaceProps) {
  const [open, setOpen] = useState(false);
  const toast = useToast();

  function saveIssue() {
    toast.show("Issue saved", { variant: "success" });
    setOpen(false);
  }

  return (
    <View>
      <Pressable accessibilityRole="button" onPress={() => setOpen(true)}>
        <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
          <Icon name="Pencil" size={18} color={theme.colors.foreground} />
          <Text style={{ color: theme.colors.foreground }}>Edit issue</Text>
        </View>
      </Pressable>

      <Modal
        title="Edit issue"
        icon={<Icon name="Pencil" size={18} color={theme.colors.foreground} />}
        open={open}
        onOpenChange={setOpen}
      >
        <Modal.Content>
          <Pressable accessibilityRole="button" onPress={saveIssue}>
            <Text style={{ color: theme.colors.foreground }}>Save</Text>
          </Pressable>
        </Modal.Content>
      </Modal>
    </View>
  );
}

Modal uses a bottom sheet on compact layouts and a centered dialog otherwise. The plugin owns the open state.

Prop	Type	Required	Behavior
`title`	`string`	Yes	Labels the modal and its visible header.
`icon`	`ReactNode`	No	Renders before the title in the header.
`open`	`boolean`	Yes	Shows the modal content when `true`.
`onOpenChange`	`(open: boolean) => void`	Yes	Receives `false` when the user dismisses it.
`children`	`ReactNode`	Yes	Contains `Modal.Content`.

Modal.Content owns the body below the host-rendered header:

Prop	Type	Default	Behavior
`children`	`ReactNode`	Required	Body content below the header.
`style`	`StyleProp<ViewStyle>`	—	Styles the full body viewport, including empty space. Use for backgrounds.
`contentContainerStyle`	`StyleProp<ViewStyle>`	Padding 24, gap 16	Overrides the content layout. Set `padding: 0, gap: 0` for edge-to-edge rows.
`scrollable`	`boolean`	`true`	The host scrolls the body. Set `false` for a bounded body with your own scroller.

A plain Modal.Content is already padded and scrollable. Avoid adding a second padded wrapper unless you want another inset. Body styles leave the host header, drag handle, and dismissal controls intact. The host reserves bottom safe-area space on compact native layouts; setting content padding to zero removes the decorative inset, not that space. Keyboard clearance is handled separately.

With scrollable={false}, the body fills the available sheet height, and the centered dialog uses 85% of the available height. Use flex: 1, minHeight: 0 on your list. Default scrolling dialogs stay content-sized on wide layouts. Presentation follows window size, including narrow desktop windows and wide tablets.

The close button, backdrop, platform back action, web Escape key, and compact sheet gesture dismiss the modal. Dismissal calls onOpenChange(false); the plugin must update open to close it.

Modal children keep the plugin runtime context. useIsee, useRpc, useWorkspace, and useAgent work inside them.

Scrolling

Import ScrollView and FlatList from @getpaseo/plugin/client/react-native when content can appear in a Isee modal. They accept React Native props and refs and integrate with the sheet's gestures. Outside a sheet they use ordinary React Native scrolling. Do not import bottom-sheet libraries directly.

Use one vertical scroll owner: either the default modal body, or your own list with scrollable={false}. A fixed-height vertical list nested inside the default scrolling body can compete with the sheet for gestures on Android. Horizontal scrolling can coexist with the host's vertical body.

Both the default body and SDK lists share native sheet gestures: drag up to expand before scrolling; drag down at the top of the list to collapse or dismiss. scrollable={false} removes the host's scroll container without changing these gestures. Expand the sheet before using list methods such as scrollToEnd; the sheet locks list offsets below its largest height.

import { FlatList, Modal } from "@getpaseo/plugin/client/react-native";
import { Text } from "react-native";

// Inside your controlled Modal:
<Modal.Content
  scrollable={false}
  style={{ backgroundColor: theme.colors.surface1 }}
  contentContainerStyle={{ padding: 0, gap: 0 }}
>
  <FlatList
    style={{ flex: 1, minHeight: 0 }}
    data={items}
    keyExtractor={(item) => item.id}
    renderItem={({ item }) => (
      <Text style={{ padding: 16, color: theme.colors.foreground }}>{item.title}</Text>
    )}
  />
</Modal.Content>;

For horizontal tabs, place <ScrollView horizontal style={{ flexGrow: 0 }}>…</ScrollView> inside the default Modal.Content. Keep the content's vertical scrolling on the host.

Copy and paste

copyText(text): Promise<void> writes to the clipboard on the device running the app. Call it from a user action and await it before reporting success. It rejects if the platform denies copying or the clipboard is unavailable; browser permissions and secure-context requirements still apply.

import { copyText, useToast } from "@getpaseo/plugin/client/react-native";

// Inside your component:
const toast = useToast();
async function copyResult() {
  try {
    await copyText(result);
    toast.show("Copied", { variant: "success" });
  } catch {
    toast.error("Could not copy. Select the text and use Copy.");
  }
}

Programmatic copying and native text selection are separate interactions. Use <Text selectable> for long-press selection and OS Copy. Import TextInput from @getpaseo/plugin/client/react-native for modal forms. It accepts React Native input props and refs, supports OS Paste, and registers focus with the native sheet so the keyboard can raise the form. Outside a sheet it uses the ordinary input. A plain React Native input supports Paste too, but does not register focus with the sheet; the keyboard can cover it. No clipboard read API is needed for OS Paste. Avoid DOM clipboard code in native plugins and the deprecated Clipboard export from react-native.

The runnable modal UI example contains a padded form, full-width rows, a virtualized list, horizontal tabs, and a copy/paste input.

Toasts

useToast() returns two methods:

Method	Behavior
`show(message, options?)`	Shows a toast for 2,200 ms unless `durationMs` is supplied.
`error(message)`	Shows an error toast for 3,200 ms.

show accepts these options:

Option	Type	Default
`variant`	`"default" \| "info" \| "success" \| "warning" \| "error"`	`"default"`
`durationMs`	`number`	`2200`

Showing another toast replaces the currently visible toast. An empty message is ignored.

Icons

Icon renders a Lucide icon from Isee's installed icon set. Plugin bundles do not import lucide-react-native or react-native-svg.

Prop	Type	Required	Behavior
`name`	`string`	Yes	Lucide icon name. Unknown names render nothing.
`size`	`number`	No	Icon width and height.
`color`	`string`	No	Icon color. Use a plugin theme token.

Timeline items

A plugin can replace an agent timeline entry with its own data and React Native renderer. Both registrations are client contributions. Isee applies the transformer while building the render model, including every live streaming update.

import type { PluginClientContext, PluginTimelineItemProps } from "@getpaseo/plugin/client";
import { Text } from "react-native";
import { z } from "zod";

const schema = z.object({ label: z.string() });

function Card({ item, theme }: PluginTimelineItemProps<z.output<typeof schema>>) {
  return <Text style={{ color: theme.colors.foreground }}>{item.data.label}</Text>;
}

export default function contribute(client: PluginClientContext) {
  client.addTimelineTransformer({
    id: "command-card",
    query: { itemType: "tool_call" },
    transform({ item, phase }) {
      return {
        items: [
          {
            type: "plugin",
            kind: "command-card",
            version: 1,
            data: { label: item.name, phase },
          },
        ],
      };
    },
  });
  client.addTimelineRenderer({
    kind: "command-card",
    version: 1,
    schema,
    Component: Card,
  });
  return () => {};
}

query.itemType is the stable, coarse selector. Inspect the selected item inside transform for provider- or tool-specific recognition. Returning undefined keeps the original entry. Returning items replaces it; an empty array removes it. Item data must be JSON-compatible. The phase input is "streaming" for the live assistant message, running tool calls, and loading reasoning; it is "complete" for committed or fetched messages and finished tools or reasoning. Assistant and reasoning callbacks receive the full accumulated text on each update, including paragraph separators. Isee invokes transformers before splitting native Markdown or grouping tools in Overview. A claimed assistant message remains one source item throughout streaming; return undefined until recognizable if the first text is insufficient to identify it. Each replacement may set an optional plugin-local id; otherwise Isee uses its index within that source item's output.

Renderers receive agentId, item, timestamp, theme, host, and layout. Isee validates item.data with the registered schema before rendering. Keep transformers synchronous and deterministic. Isee memoizes results by source-item reference and derives replacement identity from the source row, so updates to one streaming item do not remount its renderer. Use the exported useRevealedText(text, phase) hook when a renderer should pace streaming text like Isee's built-in assistant rows.

Append a timeline row from the daemon

A server handler can add a plugin-owned row to canonical history:

import type { PluginHandlerContext } from "@getpaseo/plugin/server";

async function publishReview(agentId: string, { paseo }: PluginHandlerContext) {
  await paseo.agents.ref(agentId).timeline.append({
    type: "plugin",
    id: "review",
    kind: "review-result",
    version: 1,
    data: { verdict: "ready" },
  });
}

Field	Type	Required	Behavior
`type`	`"plugin"`	Yes	Selects the plugin timeline variant.
`id`	`string`	Yes	Stable plugin-local identity. Reusing it replaces the old row.
`kind`	`string`	Yes	Selects the registered renderer.
`version`	positive integer	Yes	Selects the renderer contract version.
`data`	JSON-compatible	Yes	Renderer payload, at most 64 KiB after JSON serialization.

The daemon stamps pluginId from the calling plugin session and rejects this RPC from non-plugin sessions. The row appears live, survives timeline refetches, and keeps only the latest value for the same plugin and id. If its renderer is missing, Isee shows the existing unavailable row. Daemons reject data over the limit rather than truncating it. Daemons that support this operation advertise server_info.features.pluginTimelineItems.

Theme and layout

Plugin UI runs on desktop, browser, iOS, and Android, across every Isee theme. theme is a typed PluginTheme mapped from the active host theme. Color and spacing must come from those props. Hardcoded colors and unstyled Text break when the host theme changes.

Recreate styles when theme or layout.compact changes.

Key	Required for	Use it for
`theme.colors.foreground`	Every primary `Text`	Titles and body copy
`theme.colors.foregroundMuted`	Secondary `Text`	Labels and supporting copy
`theme.colors.surface0`	Root view	Panel background
`theme.colors.surface1`	Raised surfaces	Cards and panels
`theme.colors.surface2`	Control surfaces	Inputs and secondary controls
`theme.colors.border`	Surface boundaries	Borders and dividers
`theme.colors.accent`	Primary action fills	Buttons and selected states
`theme.colors.accentForeground`	Text on an accent fill	Button labels
`theme.colors.statusSuccess`	Success feedback	Success messages and indicators
`theme.colors.statusWarning`	Warning feedback	Warning messages and indicators
`theme.colors.statusDanger`	Failure copy	Error messages and destructive text
`layout.compact`	Padding and stacking	`true` on mobile and narrow windows
`layout.platform`	Platform-specific behavior	`ios`, `android`, or `web`

Do not hardcode #000, #fff, or React Native's default text color. Primary copy uses foreground. Labels use foregroundMuted. Tighten padding when layout.compact is true.

Workspace and agent panels receive the same theme, layout, and optional navigation fields.

Contribute a theme

addTheme adds a light or dark theme to Settings → Appearance, listed under the built-ins by its name. A theme is data, so it needs no component file:

import type { PluginClientContext } from "@getpaseo/plugin/client";

export default function contribute(client: PluginClientContext) {
  client.addTheme({
    id: "mocha",
    name: "Catppuccin Mocha",
    appearance: "dark",
    colors: {
      background: "#1e1e2e",
      foreground: "#cdd6f4",
      raised: "#313244",
      control: "#45475a",
      border: "#45475a",
      accent: "#cba6f7",
      mutedForeground: "#a6adc8",
      ring: "#6c7086",
    },
  });
  return () => {};
}

Every color is a hex string; anything else fails to load. Isee expands the palette into the full token set the built-in dark themes use, so a contributed theme covers panels, menus, diffs, status colors, and the terminal without listing them.

Color	Becomes
`background`	App, workspace, and terminal background
`foreground`	Primary text, terminal foreground and cursor
`raised`	Cards, popovers, and hovered rows
`control`	Inputs, secondary fills, and the light-theme sidebar
`border`	Borders and the highest raised-surface tint
`accent`	Buttons, selection, and focus. Optional; `foreground` if omitted.
`mutedForeground`	Secondary text
`ring`	Focus rings, scrollbars, and terminal bright black

appearance is "light" or "dark". Isee uses it to select the matching surface, status, diff, syntax, terminal, and shadow derivation.

Only one contributed theme is active at a time. Selecting one persists the choice; if the plugin is later disabled or removed, Isee falls back to the default theme rather than leaving the app unpainted.

Themes need a host that supports them. A client released before addTheme cannot evaluate that client entry and reports client.addTheme is not a function. Update the client.

Settings screens

Register a component with client.addSettingsScreen({ id, title, icon, Component }) in index.client.tsx. It appears under Settings → Plugins → your plugin on that host. id is unique within the installation; icon is a Lucide name. Registration returns an idempotent remover, and plugin teardown removes remaining screens.

Call client.openSettings(id) or a Command Center callback's openSettings(id) to open one of your own screens. Each installation has its own values and route, even when several hosts install the same plugin.

The component receives PluginSurfaceProps. Isee owns the header, back navigation, safe areas, scrolling, and the centered settings column. Compact windows push a full-screen detail; wide windows keep the settings sidebar. Render content inside that frame using React Native components. A disabled or removed plugin leaves an unavailable screen with working Back navigation.

Named UI components

Import settings components from @getpaseo/plugin/client/ui. They work with your own state and RPCs; no form wrapper or storage binding is required.

import { useState } from "react";
import { SettingsCard, SettingsSection, SettingsSwitch } from "@getpaseo/plugin/client/ui";

export function DisplaySettings() {
  const [visible, setVisible] = useState(true);
  return (
    <SettingsSection title="Display">
      <SettingsCard>
        <SettingsSwitch label="Show metadata" value={visible} onValueChange={setVisible} />
      </SettingsCard>
    </SettingsSection>
  );
}

Component	Props and behavior
`SettingsGroup`, `SettingsSection`	Required `title`, `children`; optional `info` tooltip, `trailing` content, `testID`. Own section spacing and headings.
`SettingsCard`	`children`, optional `testID`. Owns the card surface and dividers between direct children. Give mapped rows stable React keys.
`SettingsRow`	Required `label`; optional `hint`, `error`, `children`, `testID`. Wrap any custom control or content.
`SettingsSwitch`	Row props plus required `value: boolean`, `onValueChange`; optional `disabled`.
`SettingsSelect`	Row props plus required string `value`, `options: { label, value }[]`, `onValueChange`; optional `disabled`. Uses Isee's adaptive menu.
`SettingsInput`	Row props plus required `onChangeText`; optional `initialValue`, `placeholder`, `disabled`, `secureTextEntry`, `ref`.
`SettingsAction`	Row props plus required `actionLabel`, `onPress`; optional `disabled`.

SettingsInput owns in-progress text. initialValue seeds it when mounted. Its ref exposes focus(), blur(), getText(), and replaceText(text) for explicit programmatic changes. Keep draft text outside persisted values until the user saves. Custom previews and controls can sit beside or inside these components.

Persisted values

Define a settings document in shared/:

import { defineSettings } from "@getpaseo/plugin";
import { z } from "zod";

export const preferences = defineSettings({
  id: "display",
  scope: "host",
  version: 1,
  schema: z.object({ showMetadata: z.boolean().default(true) }),
});

Register it in index.server.ts before returning cleanup. The returned handle lets server code read the document and react to changes. A screen using its own data can remain client-only.

export default function contribute(server: PluginServerContext) {
  const settings = server.registerSettings(preferences);

  settings.subscribe((next) => {
    if (next.status === "ready") {
      console.log("Settings changed", next.revision);
    }
  });

  return () => {};
}

Definition field	Contract
`id`	Lowercase identifier matching `[a-z][a-z0-9_-]*`; unique within the installation.
`scope`	Required `"host"`. All authorized clients of that host share the document. No per-user, device-local, or cross-host synchronization.
`version`	Required positive integer describing the schema, independent of the write revision.
`schema`	Zod schema for JSON values. Supply defaults so parsing `{}` produces a complete document.
`migrate(values, fromVersion)`	Optional synchronous or asynchronous conversion from an older stored version. Its output must pass the current schema.

Call useSettings(preferences) in any contributed component. It returns a discriminated state:

`status`	Available data
`loading`	Read is pending; do not render default values as though they were saved.
`ready`	Typed `values` and an opaque `revision`.
`invalid`	`error` and `revision`; stored data is preserved.
`error`	`error` from the read/connection.

The server handle exposes read() and subscribe(). read() returns the same ready or invalid state as the client hook, including the opaque revision. subscribe() returns a cleanup function and receives a new ready state after a successful save, reset, or migration. Invalid writes and revision conflicts do not notify subscribers. Listener failures are logged without turning a committed write into a failed save.

const current = await settings.read();
if (current.status === "ready") {
  // Use current.values and current.revision.
}

Every state also exposes saving, saveError, and these actions:

save(values, revision): Promise<boolean> validates and saves a complete document. Returns false and sets saveError on validation, conflict, or transport failure; it does not throw.
reset(): Promise<boolean> explicitly replaces the document with schema defaults, using the revision loaded by the hook. It can recover invalid stored data.
reload(): Promise<void> clears the save error and reads again. Your component owns its draft; reloading does not discard that draft automatically.

For an immediate toggle, pass { ...settings.values, showMetadata } and settings.revision to save. For a draft editor, capture both the values and revision when opening it. Keep that revision until a save succeeds or the user discards the draft. A stale revision rejects the save, preserving both the draft and the newer saved values.

Writes are atomic and validated on the host. Connected clients receive updates without reloading the plugin. Values survive daemon restart, plugin reload, disable, and updates. Removing an installation deletes its settings. Reinstalling that ID starts from defaults.

A missing document uses schema defaults. Invalid data, failed migrations, and unsupported newer versions produce invalid without silently resetting the file. Successful migrations persist the new version once. These documents are ordinary host-side JSON, not a credential vault. Settings RPCs use the existing daemon.manage permission for plugin execution.

See the complete settings example for immediate controls, a draft editor with validation, custom content, and Command Center navigation.

Workspace panels

client/review.tsx:

import { type PluginAgentPanelProps, useAgent, useWorkspace } from "@getpaseo/plugin/client";
import { useMemo } from "react";
import { Text, View } from "react-native";

export function ReviewPanel({ theme, layout, workspaceId, agentId }: PluginAgentPanelProps) {
  const workspaceName = useWorkspace(workspaceId, (workspace) => workspace.name);
  const agent = useAgent(agentId, ({ id, title }) => ({ id, title }));
  const styles = useMemo(
    () => ({
      screen: {
        flex: 1,
        padding: layout.compact ? 16 : 24,
        backgroundColor: theme.colors.surface0,
      },
      title: { color: theme.colors.foreground },
      detail: { color: theme.colors.foregroundMuted },
    }),
    [theme, layout.compact],
  );
  return (
    <View style={styles.screen}>
      <Text style={styles.title}>{workspaceName}</Text>
      <Text style={styles.detail}>{agent?.title ?? agent?.id}</Text>
    </View>
  );
}

index.client.tsx:

import type { PluginClientContext } from "@getpaseo/plugin/client";
import { ReviewPanel } from "./client/review";

export default function contribute(client: PluginClientContext) {
  client.addWorkspacePanel({
    id: "review",
    title: "Review",
    icon: "Scan",
    context: "agent",
    locations: ["workspace", "explorer"],
    Component: ReviewPanel,
  });
  return () => {};
}

addWorkspacePanel fields:

Field	Required	Meaning
`id`	Yes	Plugin-local panel ID.
`title`	Yes	Workspace-tab title.
`icon`	Yes	Lucide icon name.
`context`	Yes	`workspace` or `agent`.
`locations`	No	`workspace` and/or `explorer`. Defaults to `workspace`.
`Component`	Yes	React Native component matching the selected context's props.

A workspace panel receives PluginWorkspacePanelProps: context: "workspace", theme, host, layout, and workspaceId. An agent panel receives PluginAgentPanelProps: context: "agent", the same common fields and workspaceId, plus agentId.

Read cached state with useWorkspace(workspaceId, selector) and useAgent(agentId, selector). A selector is required. Isee compares its result shallowly, so selecting { name, status } does not re-render when unrelated fields change. Select every field the component renders in one call; do not select the whole snapshot.

Both hooks return null when the record is unavailable. Otherwise they run synchronously against normalized client state. Snapshot DTOs and their nested values are deeply readonly and frozen at runtime. Do not call plugin RPC to discover the current workspace or agent. Fetch optional or vendor-specific enrichment after the component renders.

Workspace snapshot fields:

Field	Type
`id`	`string`
`projectId`	`string`
`projectDisplayName`	`string`
`projectRootPath`	`string`
`directory`	`string`
`projectKind`	`"git" \| "non_git" \| "directory"`
`kind`	`"directory" \| "local_checkout" \| "checkout" \| "worktree"`
`name`	`string`
`title`	`string \| null`
`status`	`"needs_input" \| "failed" \| "running" \| "attention" \| "done"`
`statusEnteredAt`	ISO timestamp or `null`
`archivingAt`	ISO timestamp or `null`
`diffStat`	`{ additions: number; deletions: number } \| null`

Agent snapshot fields:

Field	Type
`id`	`string`
`workspaceId`	`string`
`provider`	`string`
`status`	`"initializing" \| "idle" \| "running" \| "error" \| "closed"`
`createdAt`	ISO timestamp
`updatedAt`	ISO timestamp
`lastActivityAt`	ISO timestamp
`title`	`string \| null`
`cwd`	`string`
`model`	`string \| null`
`currentModeId`	`string \| null`
`thinkingOptionId`	`string \| null`
`requiresAttention`	`boolean`
`attentionReason`	`"finished" \| "error" \| "permission" \| null`
`parentAgentId`	`string \| null`
`labels`	`Record<string, string>`

Isee owns tab focus, splitting, closing, persistence, query state, the API/RPC providers, and the render error boundary. A restored tab whose plugin, panel, context, workspace, or agent is unavailable stays open with an unavailable message instead of crashing the workspace.

Command Center items

Open the Command Center with ⌘K on macOS or Ctrl+K on Windows and Linux, then search for the item title.

import { defineRpc } from "@getpaseo/plugin";
import { z } from "zod";

const refreshReview = defineRpc({
  name: "review.refresh",
  input: z.object({ agentId: z.string(), scope: z.string().optional() }),
  output: z.object({ refreshed: z.boolean() }),
});

client.addCommandCenterItem({
  id: "open-review",
  title: "Open review",
  icon: "Scan",
  keywords: ["inspect"],
  context: "agent",
  async onSelect({ paseo, rpc, workspace, agent, openPanel }) {
    await paseo.workspaces.ref(workspace.id).setTitle(`Review ${agent.id}`);
    await rpc(refreshReview, { agentId: agent.id });
    openPanel("review");
  },
});

addCommandCenterItem fields:

Field	Required	Meaning
`id`	Yes	Plugin-local item ID.
`title`	Yes	Search result title.
`icon`	Yes	Lucide icon name.
`keywords`	No	Additional Command Center search terms.
`context`	Yes	`global`, `workspace`, or `agent`.
`onSelect`	Yes	Client-side callback for the matching context.

Global items appear on the installation's selected host. Workspace items appear only when that host has an active cached workspace. Agent items appear only when the focused workspace tab is an agent or an agent-context plugin panel whose cached record belongs to that workspace. Missing context removes the item rather than calling the plugin to discover it.

Every callback receives:

Field	Context	Meaning
`context`	All	Matching discriminator.
`paseo`	All	Selected host's existing `IseeApi`.
`rpc(contract, input)`	All	Typed call to this installation's daemon-side plugin handler.
`openSurface(id)`	All	Opens one of this plugin's registered global surfaces.
`workspace`	Workspace and agent	Synchronous workspace snapshot.
`agent`	Agent	Synchronous matching agent snapshot.
`openPanel(id, options?)`	Workspace and agent	Opens a registered panel in the callback's current context. Pass `{ location: "explorer" }` to target Explorer.

An agent callback may open either an agent panel or a workspace panel. A workspace callback may open only a workspace panel. Unknown surface and panel IDs fail visibly. Use paseo for normal workspace, agent, provider, and daemon-config operations. Use rpc for plugin-specific filesystem, credential, vendor, or daemon-local work.

Slash commands

Register a command that runs in the Isee client when the user submits /name args from the message composer. The text is never sent to the agent:

client.addSlashCommand({
  name: "review",
  description: "Run the review bot",
  argumentHint: "[scope]",
  context: "agent",
  async onSubmit({ args, agent, rpc, openPanel }) {
    await rpc(refreshReview, { agentId: agent.id, scope: args });
    openPanel("review");
  },
});

Field	Required	Meaning
`name`	Yes	Command name without the leading slash.
`description`	Yes	Composer autocomplete description.
`argumentHint`	Yes	Short usage hint shown after the command name.
`context`	Yes	`"workspace"` or `"agent"`.
`onSubmit`	Yes	Client callback for the matching context.

onSubmit receives the matching Command Center callback context plus args. For /review src, args is "src"; Isee trims only the remainder's leading and trailing whitespace and leaves parsing to the plugin. Isee owns the autocomplete row, input clearing, and the error toast. It does not wait for onSubmit or show a pending state; use a composer pill or panel for that.

Precedence is built-in client commands, plugin commands, then provider commands. A lower-precedence collision is omitted. Built-in aliases also reserve their names. The first plugin in stable catalog order wins a collision between plugins. Commands do not run while the composer has attachments.

Header buttons

Try the button example for actions, menus, custom icons and content, and visibility updates in both the header and composer. It switches one header button between modes; additional actions use a named Tools menu.

client.addHeaderButton({ id, workspaceId, button }) adds a button before the built-in actions on the workspace header's right side. It returns a registration with update(patch) and remove().

const review = client.addHeaderButton({
  id: "review",
  workspaceId,
  button: {
    title: "Open review",
    icon: "Scan",
    label: "Review",
    behavior: {
      kind: "action",
      onPress() {
        client.openPanel("review", { workspaceId });
      },
    },
  },
});

review.update({ label: "Review · 3" });
review.update({ visible: false });
review.update({ visible: true });
review.remove();

Omit label for an icon-only header button. Menus and popovers show a chevron on wide layouts. Compact header buttons use icons without labels or chevrons. Isee moves excess contributions into a shared overflow menu. Placement and overflow are host decisions.

Composer pills

client.addComposerPill({ id, workspaceId, agentId, button }) uses the same button descriptor and returns the same registration. It targets one agent's composer track alongside Tasks and Subagents. Composer pills always show the icon and label (or title when label is omitted). They never show a chevron, including for menus and popovers.

const pill = client.addComposerPill({
  id: "review",
  workspaceId,
  agentId,
  button: {
    title: "Open review",
    icon: "Scan",
    label: "Review",
    behavior: {
      kind: "action",
      onPress() {
        client.openPanel("review", { workspaceId, agentId });
      },
    },
  },
});

For pills that follow the agent directory, use an explicit owned list subscription. The local plugin example replaces registrations on each snapshot and aborts the observation during entry cleanup, including pending bootstrap.

Button descriptor

These contracts are exported from @getpaseo/plugin/client.

Field	Required	Meaning
`title`	Yes	Non-empty accessible label, tooltip, and sheet title.
`icon`	Yes	Lucide name or `ComponentType<PluginButtonIconProps>`.
`label`	No	Non-empty display text. Omit to use the placement's default.
`visible`	No	Defaults to `true`. False removes the trigger and its layout space.
`disabled`	No	Defaults to `false`. Keeps the button visible and prevents interaction.
`behavior`	Yes	One of the three shapes below.

type PluginButtonBehavior =
  | { kind: "action"; onPress(): void | Promise<void> }
  | { kind: "menu"; items: readonly PluginButtonMenuEntry[] }
  | { kind: "popover"; Content: React.ComponentType<PluginButtonContentProps> };

An action runs on the client. Isee marks the button busy until its promise settles, blocks repeated presses, and shows failures in a toast. A failed action can be retried. Use the client's paseo for ordinary operations and rpc for plugin-specific backend work.

Menus and popovers open anchored surfaces on wide layouts and bottom sheets on compact layouts. The whole trigger opens the surface; there is no split-button behavior.

A menu contains items and separators. IDs use lowercase letters, digits, and hyphens, start with a letter, and are unique within that menu.

const behavior: PluginButtonBehavior = {
  kind: "menu",
  items: [
    {
      kind: "item",
      id: "refresh",
      title: "Refresh review",
      icon: "RefreshCw",
      behavior: { kind: "action", onPress: refreshReview },
    },
    { kind: "separator", id: "details-divider" },
    {
      kind: "item",
      id: "details",
      title: "Review details",
      behavior: { kind: "popover", Content: ReviewDetails },
    },
  ],
};

An item requires kind: "item", id, title, and behavior. Its optional icon, visible, and disabled follow the button rules. A separator contains only kind: "separator" and id. Isee removes leading, trailing, and consecutive separators after filtering hidden items.

Items can use all three behaviors. Nested menus open flyouts on wide layouts and pages with back navigation within the same compact sheet. Custom content pages open on selection, never hover. Choosing an action closes the menu; opening another page keeps it open.

PluginButtonIconProps contains theme, host, layout, size, color, and the target context. Render a React Native icon or indicator within the supplied size. Isee bounds the icon slot and owns all pointer interaction. The icon component can use plugin hooks.

PluginButtonContentProps contains theme, host, layout, the target context, and close(). Render the body only; Isee owns anchoring, scrolling, padding, and sheet presentation. Content can use useIsee, useRpc, useWorkspace, useAgent, and the installation's React Query cache.

The target context is one of:

{ context: "workspace", workspaceId: string } // Header button
{ context: "agent", workspaceId: string, agentId: string } // Composer pill

Updates and lifecycle

Each registration belongs to one plugin installation, placement, workspace, and (for pills) agent. id is plugin-local within that target and uses the same format as menu IDs. The same ID may be used in different targets or placements. Duplicate registration in the same target throws.

update(patch: Partial<PluginButton>) changes the descriptor in place, preserving identity and order. When changing behavior, supply the complete new behavior object. Invalid updates throw without changing the existing button. Subscribe to your own model or the client API and call update to publish reactive changes; mutating the original descriptor does not update the UI.

Hiding or disabling a button closes its surface. Updating its behavior also closes the surface. Hiding preserves the registration, so showing it again restores its position. It does not cancel an action already in progress.

remove() is idempotent. Updates after removal do nothing. Isee removes outstanding buttons when the plugin installation or host connection is torn down. Return cleanup from the client entry for your subscriptions, timers, and other resources.

Use the Isee SDK

Use useIsee() for ordinary Isee operations from a surface. It borrows the selected host's existing connection; do not create another client.

import { type PluginSurfaceProps, useIsee } from "@getpaseo/plugin/client";
import { Pressable, Text } from "react-native";

function PullRequestAction({ theme }: PluginSurfaceProps) {
  const paseo = useIsee();

  async function createReviewWorkspace() {
    const workspace = await paseo.workspaces.create({
      title: "Review PR 42",
      source: {
        kind: "worktree",
        cwd: "/absolute/path/to/repository",
        action: "checkout",
        checkoutSource: { kind: "change_request", forge: "github", number: 42 },
      },
    });
    await workspace.agents.create({
      config: { provider: "codex/gpt-5.5" },
      prompt: "Review PR #42.",
    });
  }

  return (
    <Pressable accessibilityRole="button" onPress={() => void createReviewWorkspace()}>
      <Text style={{ color: theme.colors.foreground }}>Create review workspace</Text>
    </Pressable>
  );
}

The returned API covers projects, workspaces, agents, terminals, providers, and daemon config. See the SDK API reference for its methods. Connection lifecycle methods are intentionally absent because Isee owns the connection.

Add plugin-specific backend behavior

Use plugin RPC only for work that is not a normal Isee operation: reading a vendor API, accessing daemon-local resources, or keeping credentials off the client.

Define one contract with Zod, handle it in the subprocess, and call it from the surface:

shared/greeting.ts:

import { defineRpc } from "@getpaseo/plugin";
import { z } from "zod";

export const greeting = defineRpc({
  name: "greeting.create",
  input: z.object({ name: z.string() }),
  output: z.object({ message: z.string() }),
});

client/greeting.tsx:

import { useRpc } from "@getpaseo/plugin/client";
import { greeting } from "../shared/greeting";

export function GreetingButton() {
  const createGreeting = useRpc(greeting);
  // Call createGreeting({ name: "Ada" }) from an event or query.
  return null;
}

server/greeting.ts:

import type { RpcInput } from "@getpaseo/plugin";
import { greeting } from "../shared/greeting";

export function createGreeting({ name }: RpcInput<typeof greeting>) {
  return { message: `Hello, ${name}` };
}

index.client.tsx:

import type { PluginClientContext } from "@getpaseo/plugin/client";
import { GreetingButton } from "./client/greeting";

export default function contribute(client: PluginClientContext) {
  client.addSurface("main", GreetingButton);
  return () => {};
}

index.server.ts:

import type { PluginServerContext } from "@getpaseo/plugin/server";
import { createGreeting } from "./server/greeting";
import { greeting } from "./shared/greeting";

export default function contribute(server: PluginServerContext) {
  server.handle(greeting, createGreeting);
  return () => {};
}

Inputs and outputs are validated on both sides. RPC names start with a lowercase letter and contain lowercase letters, numbers, dots, hyphens, or underscores. useRpc() returns a typed async function. Use TanStack Query for request state, caching, and mutations.

Backend handlers receive the same IseeApi as { paseo }. Their connection belongs to the subprocess and closes when the plugin stops. It does not subscribe to timelines or catalog events until plugin code subscribes. Follow the SDK event contract for cleanup and timeline replacements. Backend code can use Node APIs and dependencies installed in the plugin directory.

Debug backend output

Backend contributions can write to stdout and stderr with normal Node logging:

console.log("Refreshing issues");
console.error("Issue refresh failed", error);

Isee adds [paseo] entries when the plugin starts loading, becomes ready, starts stopping, and has stopped. It records compilation and load failures as stderr entries, including failures that happen before the plugin subprocess starts. Isee also captures output emitted during initialization, RPC handlers, cleanup, and process failure. Protocol traffic uses a separate channel, so console.log() cannot corrupt plugin RPCs.

Open Settings → Plugins → Logs for the plugin, or inspect the same recent tail from the daemon CLI:

paseo plugin logs my-plugin
paseo plugin logs my-plugin --json
paseo --host <url> plugin logs my-plugin

The command returns a snapshot rather than following live output. Refresh the settings view or run the command again for newer entries. Each entry includes its timestamp, stdout or stderr stream, sequence, and message.

Isee retains up to 500 entries and 256 KiB per plugin in memory. Individual lines are capped at 16 KiB. Reload, disable, compilation failure, initialization failure, and process failure retain the tail. Removing the plugin clears it, and a daemon restart starts a new tail. Structured copies are also written to the daemon log at $PASEO_HOME/daemon.log.

Only daemon-side output is captured. Logs from client surfaces remain in the app runtime. Do not log credentials, access tokens, or other secrets: connected users can read the retained tail, and the daemon log persists it.

Add a composer attachment source

An attachment source searches external resources and returns a stable text snapshot for an agent prompt. Keep credentials and vendor calls in the backend handler.

shared/issues.ts:

import { defineAttachmentSource, defineRpc } from "@getpaseo/plugin";
import { z } from "zod";

export const searchIssues = defineRpc({
  name: "issues.search",
  input: z.object({ query: z.string() }),
  output: z.object({
    items: z.array(
      z.object({
        id: z.string(),
        identifier: z.string(),
        title: z.string(),
        subtitle: z.string().optional(),
        url: z.string().url(),
        text: z.string(),
        resourceType: z.string(),
      }),
    ),
  }),
});

export const issues = defineAttachmentSource({
  id: "issues",
  title: "Acme issue",
  icon: "CircleDot",
  pickerTitle: "Attach Acme issue",
  searchPlaceholder: "Search by identifier or title",
  search: searchIssues,
});

server/issues.ts:

import type { RpcInput } from "@getpaseo/plugin";
import { searchIssues } from "../shared/issues";

export function search({ query }: RpcInput<typeof searchIssues>) {
  return searchAcmeIssues(query);
}

index.client.tsx:

import type { PluginClientContext } from "@getpaseo/plugin/client";
import { issues } from "./shared/issues";

export default function contribute(client: PluginClientContext) {
  client.addAttachmentSource(issues);
  return () => {};
}

index.server.ts:

import type { PluginServerContext } from "@getpaseo/plugin/server";
import { search } from "./server/issues";
import { searchIssues } from "./shared/issues";

export default function contribute(server: PluginServerContext) {
  server.handle(searchIssues, search);
  return () => {};
}

Isee owns the composer menu, search picker, selected pill, draft state, and submission. The text value is the complete snapshot sent to the agent.

Hosts and lifecycle

Plugins are installed per daemon. When the same contribution exists on several connected hosts, Isee shows one sidebar item and adds a host picker. The selected host supplies the bundle, Isee API, RPC transport, and query cache. Calls never fall through to another host when the selected host is offline.

Attachment sources remain scoped to each composer's host.

Workspace panels and Command Center items stay scoped to the active host and exact cached context. Reload replaces their registrations. Disable, removal, host disconnect, and evaluation failure remove Command Center items and clear the installation's query state. An already-restored panel tab remains as unavailable until its matching contribution returns or the user closes it. Panel render failures stay inside the plugin error boundary.

CLI reference

paseo plugin init /absolute/path/to/plugin
paseo plugin install /absolute/path/to/plugin
paseo plugin install /absolute/path/to/plugin --id another-runtime-id
paseo plugin add owner/repository
paseo plugin add https://git.example.com/owner/repository.git --ref main
paseo plugin add owner/monorepo:plugins/review
paseo plugin ls [id]
paseo plugin update <id>
paseo plugin update --all
paseo plugin reload my-plugin
paseo plugin logs my-plugin
paseo plugin disable my-plugin
paseo plugin enable my-plugin
paseo plugin remove my-plugin

ls reports runtime state, source details, and the installed commit without contacting the remote. Use update when you want Isee to contact a tracked Git remote and install an available update.

Put --host <url> before a management command when the target is not the CLI's default daemon. remove never deletes a directory source; it deletes the managed checkout for a Git source. The install-time --id is the runtime ID and allows the same directory or repository to be installed more than once.

Trust every plugin you add. paseo plugin add and paseo plugin install mean “I trust this codebase.” Server code and Git preparation commands run unsandboxed with the daemon user's access on the daemon host; client contributions run inside Isee. Dependencies and future updates are part of that decision. With the global --host option, commands run on the remote daemon host.

An existing directory wins over owner/repository GitHub shorthand. Append :relative/path when the plugin lives below the repository root. Omit --ref to track the default branch. Explicit branches track updates; tags and commits stay pinned.

Most plugins should omit build. Use it only when the staged checkout must install a dependency that Isee does not provide, generate source or assets, or perform another required preparation step:

{
  "id": "review",
  "requirements": { "paseo": ">=0.8.0" },
  "build": [
    ["npm", "ci"],
    ["npm", "run", "build"]
  ]
}

build is a list of non-empty argv arrays. Isee runs each executable directly, without a shell, from the staged plugin directory after resolving the exact commit and manifest. It never infers a package manager or commands from lockfiles. Install and update both run build before validation, compilation, activation, or replacement. A failing command reports its output, discards the candidate, and leaves the installed/running version intact. The daemon log records each command and output; with the global --host option, execution is on that daemon host.

Run npm run typecheck before install or reload. Manage plugin source entries with the CLI or Settings.

The daemon-wide Enable plugins switch lives under Settings → Plugins. A configured plugin remains disabled until that switch and the plugin's own enabled state are both on.

The switch is the root pluginsEnabled field in config.json. After changing it, run paseo reload --json. Enabling starts every configured plugin whose own enabled value is not false; disabling tears down all plugins. No daemon restart is required. Manual edits to plugin source entries are not reloaded; use the plugin lifecycle commands for those.

Load failures

Use paseo plugin ls to read the current status and error.

Symptom	Check
`This plugin was made for an older version of Isee`	The directory has only an `index.ts` entry. Follow the migration guide.
`Plugin entry points are missing`	Neither `index.client.tsx` nor `index.server.ts` exists with that exact name.
`server-only module cannot be imported into the plugin client bundle`	Client code imports `server/`. Move the work behind an RPC and import its contract from `shared/`.
`client-only module cannot be imported into the plugin server bundle`	Server code imports `client/`. Register that contribution from `index.client.tsx` instead.
`Node module cannot be imported into the plugin client bundle`	Client code imports `node:*`. Move the operation to `server/` and call it through an RPC.
Sidebar item is missing	The plugin is `running`, the item references an existing surface, the icon name is valid, and the client is on the installation's host.
Client module is unavailable	Import only the host-provided client modules listed above.
RPC rejects	Check both Zod schemas and the daemon-side handler error.
Edited code does not appear	Run `npm run typecheck`, then `paseo plugin reload <id>`.
Reload fails	Read `paseo plugin ls` and `paseo plugin logs <id>`, fix the source error, then reload; Isee does not restore the previous bundle.
Plugin exits unexpectedly	Read `paseo plugin logs <id>` for retained initialization, cleanup, stderr, and final crash output.

#Plugin reference

#Project files

#Requirements

#Runtime entries

#Runtime modules

#Client runtime

#Cross-platform rules

#Server runtime

#Providers

#Entry point and cleanup

#Lifecycle hooks

#Change configuration and inject an MCP server

#Inject environment variables on every session opening

#Choose workspace isolation

#Send a follow-up when a turn ends

#Answer a permission request

#Events

#Before hooks

#Ordering and returned values

#Context and cleanup

#Complete examples

#Surfaces and sidebar items

#Host UI

#Modal

#Scrolling

#Copy and paste

#Toasts

#Icons

#Timeline items

#Append a timeline row from the daemon

#Theme and layout

#Contribute a theme

#Settings screens

#Named UI components

#Persisted values

#Workspace panels

#Command Center items

#Slash commands

#Header buttons

#Composer pills

#Button descriptor

#Menu entries

#Custom icons and popover content

#Updates and lifecycle

#Use the Isee SDK

#Add plugin-specific backend behavior

#Debug backend output

#Add a composer attachment source

#Hosts and lifecycle

#CLI reference

#Load failures

Plugin reference

Project files

Requirements

Runtime entries

Runtime modules

Client runtime

Cross-platform rules

Server runtime

Providers

Entry point and cleanup

Lifecycle hooks

Change configuration and inject an MCP server

Inject environment variables on every session opening

Choose workspace isolation

Send a follow-up when a turn ends

Answer a permission request

Events

Before hooks

Ordering and returned values

Context and cleanup

Complete examples

Surfaces and sidebar items

Host UI

Modal

Scrolling

Copy and paste

Toasts

Icons

Timeline items

Append a timeline row from the daemon

Theme and layout

Contribute a theme

Settings screens

Named UI components

Persisted values

Workspace panels

Command Center items

Slash commands

Header buttons

Composer pills

Button descriptor

Menu entries

Custom icons and popover content

Updates and lifecycle

Use the Isee SDK

Add plugin-specific backend behavior

Debug backend output

Add a composer attachment source

Hosts and lifecycle

CLI reference

Load failures