paseo/public-docs/plugins/reference.md

title, description, nav, order, category

title	description	nav	order	category
Plugin reference	Local plugin files, client and server runtimes, platform limits, contributions, RPCs, lifecycle, hosts, and CLI commands.	Reference	46	Plugins

Plugin reference

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

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

Plugin code is trusted and unsandboxed. Client surfaces run in the Paseo 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.ts
  main.client.tsx
  paseo-plugin.d.ts
  package.json
  tsconfig.json

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

{ "id": "my-plugin" }

The entry point is index.ts at the plugin root. Plugin, surface, sidebar-item, workspace-panel, Command Center item, and attachment-source IDs start with a lowercase letter and contain lowercase letters, numbers, or hyphens.

The generated declaration file supplies @getpaseo/plugin, @getpaseo/plugin/react-native, and @getpaseo/plugin/server types for local typechecking. Paseo supplies the runtime modules. Regenerate a fresh project with the matching CLI when the plugin contract changes.

Add runtime-specific files as the plugin grows:

my-plugin/
  action.shared.ts
  action.server.ts
  panel.client.tsx

Suffix	Use it for
*.client.tsx	React, React Native, hooks, styles, surfaces, panels, and callbacks.
*.server.ts	Node APIs, local resources, credentials, and RPC handlers.
*.shared.ts	Zod RPC contracts and plain values imported by both runtimes.

Runtime modules

Paseo builds separate client and server bundles from index.ts. It rejects imports from *.server files into client modules and imports from *.client files into server modules. Keep shared modules free of Node and React Native runtime code.

Client runtime

Paseo provides these modules to client code:

Module	Use it for
@getpaseo/plugin	Contribution contracts and data hooks
@getpaseo/plugin/react-native	Paseo UI components and UI hooks
@getpaseo/plugin/server	Shared RPC and attachment contracts
@tanstack/react-query	Request state and caching
react	Components and hooks
react/jsx-runtime	Compiled JSX
react-native	Cross-platform UI
zod	Shared schemas

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; Paseo validates the name and renders the icon.

Client components are React Native components rendered by Paseo. Web clients render them through React Native Web. Browser globals such as localStorage and location exist only when layout.platform === "web"; iOS and Android have no equivalent. Gate any use on that field.

There is no plugin storage API. Browser storage does not persist settings across Paseo clients. There is also no general host navigation API: plugin code cannot open native Paseo routes. Command Center callbacks can only open surfaces and panels registered by the same plugin.

Server runtime

Paseo provides @getpaseo/plugin, @getpaseo/plugin/server, 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 in *.server.ts files.

Entry point and cleanup

index.ts wires contributions together and default-exports one contribution function. It must return cleanup, even when it has nothing to clean:

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

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

Cleanup can be async. Release timers, watchers, sockets, and other resources created by the plugin. Paseo 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.

Surfaces and sidebar items

Register a component, then point a sidebar item at its surface ID:

main.client.tsx:

import type { PluginSurfaceProps } from "@getpaseo/plugin";
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.ts:

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

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

PluginSurfaceProps contains:

Field	Meaning
theme	Typed PluginTheme color tokens for the active Paseo 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.

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

Host UI

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

import type { PluginSurfaceProps } from "@getpaseo/plugin";
import { Icon, Modal, useToast } from "@getpaseo/plugin/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

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	Required	Behavior
children	ReactNode	Yes	Renders the plugin's React Native UI content.

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. usePaseo, useRpc, useWorkspace, and useAgent work inside them.

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 Paseo'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 a projected timeline entry with its own data and React Native renderer. Both registrations are client contributions. A matching live event refreshes the projected tail before replacement, so provider lifecycle deltas are never exposed as plugin items.

import type { PluginContext, PluginTimelineItemProps } from "@getpaseo/plugin";
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(plugin: PluginContext) {
  plugin.addTimelineTransformer({
    id: "command-card",
    query: { itemType: "tool_call" },
    transform({ item }) {
      if (item.status === "running") return;
      return {
        items: [
          {
            type: "plugin",
            kind: "command-card",
            version: 1,
            data: { label: item.name },
          },
        ],
      };
    },
  });
  plugin.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.

Renderers receive agentId, item, timestamp, theme, host, and layout. Paseo validates item.data with the registered schema before rendering. Keep transformers synchronous and deterministic because Paseo reruns them while reconciling projected history.

Check navigation before showing an action that depends on it. Older Paseo clients leave the capability undefined. Let Paseo own route construction so the action works without reloading on desktop, browser, iOS, and Android.

Theme and layout

Plugin UI runs on desktop, browser, iOS, and Android, across every Paseo 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 client file:

import type { PluginContext } from "@getpaseo/plugin";

export default function contribute(plugin: PluginContext) {
  plugin.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. Paseo 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". Paseo 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, Paseo falls back to the default theme rather than leaving the app unpainted.

Themes need a host that supports them. A daemon released before addTheme compiles the call into the plugin's backend bundle, where it does not exist, and the plugin fails to start with plugin.addTheme is not a function. Update the host.

Workspace panels

Register one panel for workspace or agent context:

review.client.tsx:

import { type PluginAgentPanelProps, useAgent, useWorkspace } from "@getpaseo/plugin";
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.ts:

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

export default function contribute(plugin: PluginContext) {
  plugin.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. Paseo 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>

Paseo 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.

Register an action and open a panel from the callback:

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

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

plugin.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 PaseoApi.
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.

Composer pills

Register a headless client entrypoint from index.ts:

import { contributeClient } from "./review.client";

export default function contribute(plugin: PluginContext) {
  plugin.addClientSide(contributeClient);
  return () => {};
}

The client entrypoint owns pill creation and removal:

import {
  Icon,
  type PluginClientContext,
  type PluginComposerPillProps,
  useAgent,
} from "@getpaseo/plugin";
import { Text } from "react-native";

function ReviewPill({ theme, agentId }: PluginComposerPillProps) {
  const agent = useAgent(agentId, ({ title }) => ({ title }));
  return (
    <>
      <Icon name="Scan" size={14} color={theme.colors.foregroundMuted} />
      <Text numberOfLines={1} style={{ color: theme.colors.foregroundMuted, flexShrink: 1 }}>
        {agent?.title ?? "Review"}
      </Text>
    </>
  );
}

export function contributeClient(client: PluginClientContext) {
  const pills = new Map<string, () => void>();
  const unsubscribe = client.paseo.agents.subscribe((update) => {
    if (update.kind !== "upsert" || !update.agent.workspaceId) return;
    const { id: agentId, workspaceId } = update.agent;
    pills.get(agentId)?.();
    pills.set(
      agentId,
      client.addComposerPill({
        id: "review",
        title: "Open review",
        workspaceId,
        agentId,
        Component: ReviewPill,
        async onPress() {
          await client.rpc(refreshReview, { agentId });
          client.openPanel("review", { workspaceId, agentId });
        },
      }),
    );
  });
  return () => {
    unsubscribe();
    for (const remove of pills.values()) remove();
  };
}

addComposerPill fields:

Field	Required	Meaning
id	Yes	Plugin-local ID within the target agent.
title	Yes	Accessible button label.
workspaceId	Yes	Workspace whose composer track owns the pill.
agentId	Yes	Agent whose composer track owns the pill.
Component	Yes	React Native component rendering the pill's icon and text.
onPress	Yes	Client-side callback.

addClientSide runs once per plugin installation in each connected app. Its context exposes paseo, typed rpc, openSurface, explicit-context openPanel, and addComposerPill. addComposerPill returns an idempotent removal function. Paseo also removes every outstanding pill when the client entrypoint, plugin installation, or host connection is torn down.

Paseo owns the pressable, shared pill chrome, pending state, error reporting, and track-bar placement. The component receives theme, host, layout, workspaceId, and agentId. Read current values with useWorkspace and useAgent. The plugin owns when the pill exists, its icon and text, and the callback. openPanel(id, { workspaceId, agentId? }) opens or focuses a panel registered by the same plugin.

Use the Paseo SDK

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

import { usePaseo } from "@getpaseo/plugin";
import { Pressable, Text } from "react-native";

function PullRequestAction() {
  const paseo = usePaseo();

  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>Create review workspace</Text>
    </Pressable>
  );
}

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

Add plugin-specific backend behavior

Use plugin RPC only for work that is not a normal Paseo 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:

greeting.shared.ts:

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

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

greeting.client.tsx:

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

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

greeting.server.ts:

import type { output as ZodOutput } from "zod";
import { greeting } from "./greeting.shared";

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

index.ts:

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

export default function contribute(plugin: PluginContext) {
  plugin.handle(greeting, createGreeting);
  plugin.addSurface("main", GreetingButton);
  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 PaseoApi as { paseo }. Their connection belongs to the subprocess and closes when the plugin stops. 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);

Paseo 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. Paseo 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 plugin logs my-plugin --host <url>

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.

Paseo 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.

issues.shared.ts:

import { defineAttachmentSource, defineRpc } from "@getpaseo/plugin/server";
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,
});

issues.server.ts:

import type { output as ZodOutput } from "zod";
import { searchIssues } from "./issues.shared";

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

index.ts:

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

export default function contribute(plugin: PluginContext) {
  plugin.handle(searchIssues, search);
  plugin.addAttachmentSource(issues);
  return () => {};
}

Paseo 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, Paseo shows one sidebar item and adds a host picker. The selected host supplies the bundle, Paseo 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 --path plugins/review
paseo plugin status [id]
paseo plugin update <id>
paseo plugin update --all
paseo plugin ls
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

Pass --host <url> to management commands 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.

An existing directory wins over owner/repository GitHub shorthand. Omit --ref to track the default branch. Explicit branches track updates; tags and commits stay pinned. Git installation runs no package manager and no install scripts. update validates and compiles the candidate before activation, then restores the installed commit if startup fails.

Run npm run typecheck before install or reload. Never edit the daemon config directly.

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
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; Paseo does not restore the previous bundle.
Plugin exits unexpectedly	Read paseo plugin logs <id> for retained initialization, cleanup, stderr, and final crash output.