Skip to main content
Agent skill

Paseo Plugin

Build and manage trusted local Paseo plugins. Use when the user asks to create, edit, install, reload, enable, disable, remove, or troubleshoot a Paseo plugin; add lifecycle hooks; transform agent configuration, environment, MCP servers, or workspace creation; automate permissions or turn follow-ups; add a screen, sidebar header or footer item, workspace panel, or file panel; add Command Center items or slash commands; add composer pills or attachment sources; transform, render, or append agent timeline items; contribute a theme; use Paseo from plugin code; or add plugin RPCs.

All install options
Quick install · Personal (~/.claude/skills)Project / Cursor / Desktop →
mkdir -p ~/.claude/skills/paseo-plugin && curl -fsSL 'https://raw.githubusercontent.com/getpaseo/paseo/main/skills/paseo-plugin/SKILL.md' -o ~/.claude/skills/paseo-plugin/SKILL.md

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Paseo Plugin when an AI agent needs a reusable SKILL.md workflow for this job: Build and manage trusted local Paseo plugins. Use when the user asks to create, edit, install, reload, enable, disable, remove, or troubleshoot a Paseo plugin; add lifecycle hooks; transform agent configuration, environment, MCP servers, or workspace creation; automate permissions or turn follow-ups; add a screen, sidebar header or footer item, workspace panel, or file panel; add Command Center items or slash commands; add composer pills or attachment sources; transform, render, or append agent timeline items; contribute a theme; use Paseo from plugin code; or add plugin RPCs.

When not to use it

Skip Paseo Plugin when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
One-line install (Claude Code)
mkdir -p ~/.claude/skills/paseo-plugin && curl -fsSL 'https://raw.githubusercontent.com/getpaseo/paseo/main/skills/paseo-plugin/SKILL.md' -o ~/.claude/skills/paseo-plugin/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/paseo-plugin/SKILL.md. For a shared project, commit the folder at .claude/skills/paseo-plugin/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Paseo Plugin skill for this task: Use Paseo Plugin when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptinferred

    The skill text mentions ChatGPT or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Paseo plugins

Build or manage the requested plugin directly. Use the current public docs to catch contract changes, but keep working from this skill if the network is unavailable.

Use the user's request and current conversation as input, including any arguments supplied with the skill invocation.

## Check current documentation

Fetch [https://paseo.sh/llms.txt](https://paseo.sh/llms.txt) first. Select and fetch the current plugin Markdown pages from that index before changing a plugin:

- [Plugin quickstart](https://paseo.sh/docs/plugins.md) ([browser page](https://paseo.sh/docs/plugins)) - [Publishing](https://paseo.sh/docs/plugins/publishing.md): npm package contents, dependencies, Git preparation, and private registries. - [Plugin reference](https://paseo.sh/docs/plugins/reference.md) ([browser page](https://paseo.sh/docs/plugins/reference))

Use the deployed docs when they disagree with this skill. Do not send the user away to read them instead of completing the work.

In the Paseo repository, use `public-docs/plugins/reference.md` for the checkout's API, including unreleased changes. Use `docs/plugins.md` for maintainer guidance. Complete contracts belong in the public docs; this skill indexes the references and examples.

## What a plugin can contribute

Pick the contribution that matches the request. Each row names the registration, when it fits, and where the full contract lives. Most plugins combine several: a slash command that calls an RPC, which appends a timeline row, which a renderer draws.

| Contribution | Registration | Use it when | Reference | | ------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Screen and sidebar item | `addScreen` + `addSidebarHeaderItem`/`addSidebarFooterItem` | A full screen of plugin UI, or sidebar header or footer rows that open a screen or popover | reference.md → Screens and sidebar items | | Workspace panel | `addWorkspacePanel` | UI that lives as a tab beside agents, terminals, files, and diffs; `locations: ["explorer"]` for the Explorer | reference.md → Workspace panels | | File panel | `addFilePanel` | View or edit a matching file inside the file tab through its file handle | reference.md → File panels; `plugin-examples/pdf-panel`, `plugin-examples/markdown-panel` | | Command Center item | `addCommandCenterItem` | A global, workspace, or agent action reachable from ⌘K | reference.md → Command Center items | | Client slash command | `addSlashCommand` | A `/command args` in the composer that runs plugin code instead of prompting the agent | reference.md → Slash commands | | Composer pill | `addComposerPill` | A per-agent button in the composer track bar next to Tasks and Subagents | reference.md → Composer pills | | Timeline transformer | `addTimelineTransformer` + `addTimelineRenderer` | Replace, explode, or hide a built-in timeline item, including while it streams | reference.md → Timeline items; `plugin-examples/timeline-items`, `plugin-examples/inline-thinking` | | Timeline row | `paseo.agents.ref(id).timeline.append(...)` | Push a plugin-owned row into an agent timeline from a server handler and update it later | reference.md → Append a timeline row from the daemon | | Attachment source | `client.addAttachmentSource` + `server.handle` | Let the user attach a searchable external resource, such as an issue, to a prompt | reference.md → Add a composer attachment source; `plugin-examples/linear` | | Theme | `addTheme` | A light or dark palette under Settings → Appearance | reference.md → Contribute a theme; `plugin-examples/catppuccin` | | Plugin RPC | `defineRpc` + `server.handle` + `useRpc` | Daemon-side work that is not a normal Paseo operation: vendor APIs, credentials, local files | reference.md → Add plugin-specific backend behavior | | Plugin subscription | `defineSubscription` + `server.handle` + `useSubscription` | A daemon handler that pushes events while a surface listens: watchers, tails, live media; a top-level `Uint8Array` rides as binary | reference.md → Stream events from the daemon; `plugin-examples/diff-watch`, `plugin-examples/media-stream` | | Lifecycle events | `server.on` | Observe agent/workspace lifecycle, inspect ended turns, and answer permission requests | [Lifecycle hooks](https://paseo.sh/docs/plugins/reference.md#lifecycle-hooks) | | Creation and launch hooks | `server.before` | `agent.create` edits saved config; `agent.session_open` contributes launch-only `env`, `tools`, `mcpServers` on every open; `workspace.create` chooses isolation | [Before hooks](https://paseo.sh/docs/plugins/reference.md#before-hooks) | | Paseo SDK | `usePaseo()` / handler `{ paseo }` | Normal Paseo operations: workspaces, agents, providers, config | reference.md → Use the Paseo SDK |

| Lifecycle task | Example | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | Log all eleven hooks | [lifecycle-logger](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-logger) | | Follow-ups, permissions, environment, provider switching, worktrees | [lifecycle-actions](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-actions) | | Inject launch-only MCP servers and save Codex sandbox/approval options | [agent-configuration](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-configuration) | | Attach a tool to selected agents | [agent-tools](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-tools) |

## Develop plugins in a local folder

Develop a plugin in a local folder that you own, the same way you develop an npm package. Install that folder by path. Paseo runs the plugin from that folder, `paseo plugin reload <id>` loads your edits, and `paseo plugin update` does not change it.

Do not edit, build, or commit inside the installation of a Git or npm plugin. That folder is Paseo's managed storage in the `plugins/` directory of the daemon home. `paseo plugin update` replaces it, and `paseo plugin remove` deletes it. Both commands discard every edit and commit in that folder.

Before you edit an installed plugin, run `paseo plugin ls <id>` and read the SOURCE column. A `git:` source, an `npm:` source, or a registry source such as `<registry host>/owner/slug` is a managed installation. Its DIRECTORY column shows the managed folder.

To develop a plugin that is installed from Git or npm:

1. Clone the source repository of the plugin into a folder outside the daemon home. For an npm plugin, find the repository in its `package.json`. 2. If SOURCE ends with `:<path>`, use that subfolder of the clone as the plugin folder. 3. If the managed folder holds edits or commits, move them into the plugin folder. 4. In the plugin folder, install the dependencies and run the `build` commands from `paseo-plugin.json`. Paseo runs `build` only for managed installations. 5. Ask the user before you remove the managed installation. `paseo plugin remove <id>` also deletes the saved settings of the plugin. 6. Run `paseo plugin remove <id>`. 7. Run `paseo plugin install /absolute/path/to/plugin-folder --id <id>` to keep the runtime ID. 8. Edit the plugin folder, and run `paseo plugin reload <id>` after each change. If a change needs a `build` command, run that command before `reload`.

## Create the project

Use an absolute path on the daemon machine. `init` writes files but does not install packages.

```bash paseo plugin init /absolute/path/to/my-plugin cd /absolute/path/to/my-plugin npm install ```

The generated project contains:

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

The manifest supplies the default install ID and supported Paseo versions:

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

Keep `requirements.paseo` correct whenever creating or editing a plugin. `init` uses `>=` followed by the CLI version. Raise the minimum when adopting newer APIs; add an upper bound when a later Paseo release is incompatible. Use npm semver ranges and explicitly include beta versions when targeting betas. Missing requirements mean `<0.8.0`; complete the 0.8 entry migration before adding `>=0.8.0`. Verify compatibility with both the daemon and the app running client contributions. See [requirements](https://paseo.sh/docs/plugins/reference#requirements).

Each runtime has its own optional entry. A plugin must have at least one. Both entries accept `.ts` or `.tsx`; use `.tsx` when an entry imports components.

| Path | Runtime | | -------------------------------- | ----------------- | | `index.client.tsx` and `client/` | App | | `index.server.ts` and `server/` | Daemon subprocess | | `shared/` | Both |

Do not put any other code modules in the plugin root.

A client import of `server/`, a server import of `client/`, and every `node:` import reachable from client code is a compile error. A relative import to another code file in the plugin root is also a compile error; move it into `client/`, `server/`, or `shared/`. Shared modules contain Zod contracts and plain values; they do not import Node or React Native runtime APIs.

Default-export one contribution function from each entry and return cleanup:

```tsx // index.client.tsx import type { PluginClientContext } from "@getpaseo/plugin/client";

export default function contribute(client: PluginClientContext) { // Register components and client callbacks here. return () => {}; } ```

```ts // index.server.ts import type { PluginServerContext } from "@getpaseo/plugin/server";

export default function contribute(server: PluginServerContext) { // Register daemon-side RPC handlers here. return () => {}; } ```

Cleanup can be async. Use it for timers, watchers, sockets, subscriptions, and other resources created by plugin code. Every client `add*` method returns an idempotent remover. Paseo calls the entry cleanup first, removes registrations that remain, rejects pending RPCs, closes the plugin session, and stops the subprocess when the plugin stops.

## Add a workspace panel

Workspace panels live beside agents, terminals, files, and diffs. Plugins run on desktop and mobile, and Paseo has multiple themes. Every `Text` must take its color from `theme.colors`. Use `layout.compact` for padding and stacking. Unstyled text is black and fails in dark themes.

```tsx import { type PluginClientContext, type PluginWorkspacePanelProps, useWorkspace, } from "@getpaseo/plugin/client"; import { useMemo } from "react"; import { Text, View } from "react-native";

function Overview({ theme, layout, workspaceId }: PluginWorkspacePanelProps) { const name = useWorkspace(workspaceId, (workspace) => workspace.name); const styles = useMemo( () => ({ screen: { flex: 1, padding: layout.compact ? 16 : 24, gap: layout.compact ? 8 : 12, backgroundColor: theme.colors.surface0, }, title: { color: theme.colors.foreground, fontSize: layout.compact ? 20 : 24 }, }), [theme, layout.compact], ); return ( <View style={styles.screen}> <Text style={styles.title}>{name}</Text> </View> ); }

export default function contribute(client: PluginClientContext) { client.addWorkspacePanel({ id: "overview", title: "Workspace overview", icon: "PanelsTopLeft", context: "workspace", Component: Overview, }); client.addCommandCenterItem({ id: "open-overview", title: "Open workspace overview", icon: "PanelsTopLeft", context: "workspace", onSelect({ openPanel }) { openPanel("overview"); }, }); return () => {}; } ```

Use `useWorkspace(id, selector)` and `useAgent(id, selector)`. Selectors are required and their results use shallow equality. Never select the whole snapshot or add an RPC to discover the active workspace or agent. Command callbacks receive the selected host's `paseo`, typed `rpc(contract, input)`, `openScreen({ screenId, params? })`, and contextual `openPanel(id)` capabilities.

## Add a screen and a sidebar item

Plugin screens use React Native primitives and work across desktop, browser, iOS, and Android. A sidebar item, in the header or the footer, is a component: render one or more `SidebarRow`s from `@getpaseo/plugin/client/ui`, with `SidebarSeparator` between groups, and call `openScreen` or `openPopover` from them. A screen's `title` is a string or a function of its `params`; its component receives the `params` it was opened with. Color text from `theme.colors` and pad from `layout.compact`.

```tsx import type { PluginClientContext, PluginScreenProps, PluginSidebarItemProps, } from "@getpaseo/plugin/client"; import { SidebarRow } from "@getpaseo/plugin/client/ui"; import { useMemo, useState } from "react"; import { Pressable, Text, View } from "react-native";

function Counter({ theme, layout }: PluginScreenProps) { const [count, setCount] = useState(0); const styles = useMemo( () => ({ screen: { flex: 1, padding: layout.compact ? 16 : 24, gap: 16, backgroundColor: theme.colors.surface0, }, count: { color: theme.colors.foreground, fontSize: layout.compact ? 36 : 48 }, button: { padding: 14, borderRadius: 10, backgroundColor: theme.colors.accent }, buttonText: { color: theme.colors.accentForeground, textAlign: "center" as const }, }), [theme, layout.compact], ); return ( <View style={styles.screen}> <Text style={styles.count}>{count}</Text> <Pressable accessibilityRole="button" accessibilityLabel={`Increment counter, currently ${count}`} onPress={() => setCount((value) => value + 1)} style={styles.button} > <Text style={styles.buttonText}>Count me in</Text> </Pressable> </View> ); }

function CounterItem({ currentScreen, openScreen }: PluginSidebarItemProps) { return ( <SidebarRow icon="ListPlus" active={currentScreen?.screenId === "main"} onPress={() => openScreen({ screenId: "main" })} /> ); }

export default function contribute(client: PluginClientContext) { client.addScreen({ id: "main", title: "Counter", Component: Counter }); client.addSidebarHeaderItem({ id: "main", title: "Counter", Component: CounterItem }); return () => {}; } ```

Icons are Lucide icon names, inline SVG (`{ svg }`), or components; see [Icons](https://paseo.sh/docs/plugins/reference.md#icons). `theme` is a typed `PluginTheme` on every screen and panel. Primary text uses `theme.colors.foreground`; labels use `theme.colors.foregroundMuted`; the root view uses `theme.colors.surface0`. `layout.compact` is true on mobile and narrow windows. Paseo owns the route, header, host picker, close action, error boundary, and per-installation query client.

Before writing imports, classify each module as shared, client, or server. Follow the [SDK import boundaries](https://paseo.sh/docs/plugins/reference.md#runtime-modules), including transitive and type dependencies. The root is shared-only; hooks and client contexts belong to `@getpaseo/plugin/client`, server contexts to `/server`, and host UI to `/client/ui`. Install dependencies locally for typechecking; Paseo supplies host runtime modules. JSX uses the automatic runtime. Do not import `/client/host` from plugin code.

## Works on mobile

Before reporting a plugin done:

- Use React Native primitives only: `View`, `Text`, `Pressable`, `ScrollView`, and `TextInput`. - Do not use HTML elements, `className`, CSS strings, or `onClick`. - Do not put `"DOM"` in `tsconfig.json` or use `/// <reference lib="dom" />`. Put DOM globals only in `client/web.ts`, declare only what that module uses, gate every export on `Platform.OS === "web"`, and provide the native alternative or a no-op. - Take colors from `theme.colors`. - Check the compact layout.

Run this audit on `client/`:

```bash rg -n "document\.|window\.|localStorage|navigator\.|<[a-z]+[ >]|className=|onClick=" client/ ```

A hit outside `client/web.ts` is a bug.

## Choose the correct API

Use the existing Paseo SDK for normal Paseo operations. Use plugin RPC only for plugin-specific backend behavior.

### Call Paseo from a surface

`usePaseo()` borrows the selected host's current connection. Never create another client inside a surface. It is the plugin's one client in every surface: release your subscriptions in your cleanup; plugin teardown ends the rest.

```tsx import { usePaseo } from "@getpaseo/plugin/client";

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.", }); }

// Wire createReviewWorkspace to a Pressable. return null; } ```

The API covers workspaces, agents, providers, and daemon config. It omits connection lifecycle because Paseo owns the connection. Consult the current [SDK reference](https://paseo.sh/docs/sdk/reference.md) for method details.

### Add daemon-side behavior

Define one Zod contract in `shared/`, register its subprocess handler in `index.server.ts`, and call it from client code with `useRpc()`:

```ts // shared/greeting.ts import { defineRpc } from "@getpaseo/plugin"; import { z } from "zod";

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

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

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

```ts // 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 () => {}; } ```

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

function Greeting() { const createGreeting = useRpc(greeting); // Use createGreeting({ name: "Ada" }) in a query, mutation, or event. return null; } ```

Inputs and outputs are validated on both sides. A top-level `Uint8Array` input or output (declared `z.instanceof(Uint8Array)`) crosses as binary; a nested one fails validation. For a stream of events, use `defineSubscription` and `useSubscription`; see [subscriptions](https://paseo.sh/docs/plugins/reference.md#subscriptions). Backend handlers receive the same `PaseoApi` as `{ paseo }`; their IPC-backed daemon session lives exactly as long as the subprocess. Backend code can use Node APIs and installed dependencies. Keep credentials, filesystem access, shell commands, and vendor API calls in the handler rather than the client surface.

Use TanStack Query for async request state, caching, and mutations.

### Contribute tools and MCP servers at session open

Use `before("agent.session_open")` for per-agent tools and plugin-owned MCP servers. Add this callback inside `contribute(server)`:

```ts server.before("agent.session_open", ({ request }) => { if (request.provider !== "codex") return; return { ...request, mcpServers: { ...request.mcpServers, company: { type: "http", url: "https://tools.example.com/mcp" }, }, }; }); ```

`tools` and `mcpServers` start empty for each plugin and accumulate across its own callbacks. They are launch-only. Use `agent.create` to edit configuration that should be saved with the agent. See [Attach tools to agents](https://paseo.sh/docs/plugins/reference.md#attach-tools-to-agents) for `defineAgentTool` and targeting, and [Inject MCP servers](https://paseo.sh/docs/plugins/reference.md#inject-mcp-servers) for server configuration and collisions.

Starting, stopping, or reloading a plugin with a session-open hook marks open agent sessions stale. Each reopens before its next idle prompt without interrupting a running turn. `await paseo.agents.ref(id).reload()` applies changes immediately and interrupts a running turn; `refresh()` only reads the current snapshot.

### Debug daemon-side behavior

Backend contributions can use normal Node logging. `console.log()` writes to the plugin's stdout; `console.error()` writes to stderr. Paseo captures both streams without interfering with plugin IPC.

Inspect recent output after install, reload, an RPC failure, or a subprocess crash:

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

The same tail is available from **Settings → Plugins → Logs**. It includes initialization, handler, cleanup, and final crash output. Reload, disable, and process failure retain the tail. Removing the plugin clears it; restarting the daemon clears the in-memory tail. Structured copies also go to the daemon log. Never log credentials or other secrets.

## Add a composer attachment source

Define a search RPC and declarative source in `shared/`, handle it on the server, and register it on the client:

```ts // shared/issues.ts import { defineAttachmentSource, defineRpc } from "@getpaseo/plugin"; import { z } from "zod";

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(), }), ), }), });

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

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

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

```tsx // 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 () => {}; } ```

Return complete text snapshots. Paseo owns the composer menu, picker, pills, drafts, and submission. Credentials and vendor calls stay in the daemon handler.

## Add a client slash command

A slash command runs plugin code in the app when the user submits `/name args`. Nothing is sent to the agent. `args` is the raw text after the command name, trimmed; parse it in the plugin.

```ts client.addSlashCommand({ name: "review", description: "Run the review bot", argumentHint: "[scope]", context: "agent", // or "workspace" so drafts get it too async onSubmit({ args, agent, rpc, openPanel }) { await rpc(startReview, { agentId: agent.id, scope: args }); openPanel("review"); }, }); ```

The callback receives the same context as the matching Command Center item plus `args`. Paseo owns the autocomplete row, input clearing, and the error toast; put pending UI in a pill or panel. Precedence is built-in client commands, then plugin commands, then provider commands; a lower-precedence collision is dropped. Commands do not run while the composer has attachments. Server-side slash commands do not exist.

## Add a composer pill

A pill is a per-agent button in the composer track bar next to Tasks and Subagents. Add and remove pills from the client entry lifecycle. `addComposerPill` exists on `PluginClientContext`.

```tsx import type { PluginButtonRegistration, PluginClientContext } from "@getpaseo/plugin/client";

export function contributeClient(client: PluginClientContext) { const pills = new Map<string, PluginButtonRegistration>(); const lifetime = new AbortController(); const register = (agent: { id: string; workspaceId?: string | null }) => { if (lifetime.signal.aborted || !agent.workspaceId) return; const agentId = agent.id; const workspaceId = agent.workspaceId; pills.get(agentId)?.remove(); pills.set( agentId, client.addComposerPill({ id: "review", workspaceId, agentId, button: { title: "Open review", icon: "Scan", label: "Review", behavior: { kind: "action", onPress() { client.openPanel("review", { workspaceId, agentId }); }, }, }, }), ); }; const removeAll = () => { for (const pill of pills.values()) pill.remove(); pills.clear(); }; // An owned list subscription delivers existing agents, then updates, and a fresh snapshot after a reconnect. void client.paseo.agents .list({ subscribe: {}, signal: lifetime.signal }) .then(({ subscription }) => { subscription.subscribe({ snapshot: ({ entries }) => { removeAll(); for (const { agent } of entries) register(agent); }, update: (message) => { if (message.type !== "agent_update") return; const update = message.payload; if (update.kind === "upsert") return register(update.agent); pills.get(update.agentId)?.remove(); pills.delete(update.agentId); }, }); return undefined; }) .catch((error) => { if (!lifetime.signal.aborted) console.error("Agent observation failed", error); }); return () => { lifetime.abort(); removeAll(); }; } ```

Call `contributeClient(client)` from `index.client.tsx`, or move its body into that entry. The `button` descriptor sets the icon, label, and behavior; Paseo owns the pressable, chrome, pending state, error reporting, and placement. `addComposerPill` returns a registration with `update()` and `remove()`. `remove()` is idempotent, and Paseo removes every pill when the plugin, client entrypoint, or host connection is torn down.

## Transform and render timeline items

Timeline transformers and renderers are client contributions. A transformer selects one built-in `AgentTimelineItem.type`, inspects the item, and returns zero or more versioned plugin items. `undefined` keeps the source item, `items` replaces it, `[]` removes it. A renderer draws one `kind` and `version` after validating `data` with its Zod schema.

```ts client.addTimelineTransformer({ id: "inline-thinking", query: { itemType: "reasoning" }, transform: ({ item, phase }) => ({ items: [ { type: "plugin", kind: "inline-thinking", version: 1, data: { text: item.text, phase } }, ], }), }); client.addTimelineRenderer({ kind: "inline-thinking", version: 1, schema: z.object({ text: z.string(), phase: z.enum(["streaming", "complete"]) }), Component: InlineThinking, }); ```

Transformers run while the render model is built, on fetched history and on every live update, so `phase` is `"streaming"` for a loading thought or running tool call. Identity comes from the source item, so a streaming item keeps its mounted component; set an output `id` when one source explodes into several items. Transformers must be synchronous and deterministic, `data` must be JSON, and a transformer that throws is logged and skipped. Render `<StreamedText text={text} phase={phase} />` from `@getpaseo/plugin/client/ui` for paced assistant text; use its `style` prop to customize text appearance. `plugin-examples/inline-thinking` replaces the thinking row with inline text; `plugin-examples/timeline-items` replaces a todo tool call with a task card.

## Append a timeline row from the daemon

A server handler can push a plugin-owned row into any agent timeline. The same renderer registration draws it.

```ts server.handle(publishReview, async ({ agentId, verdict }, { paseo }) => { await paseo.agents.ref(agentId).timeline.append({ type: "plugin", id: "review", kind: "review-result", version: 1, data: { verdict }, }); return {}; }); ```

The daemon stamps `pluginId` from the plugin session, so only plugin code can call this. Re-appending with the same `id` replaces the earlier row live and on refetch, which is how a plugin updates a row. `data` is capped at 64 KiB serialized and rejected above that. Rows live in the daemon's in-memory timeline and survive scroll, refetch, and reconnect, but not a daemon restart. A row whose plugin is missing renders an unavailable placeholder. Hosts advertise support through `server_info.features.pluginTimelineItems`.

## Contribute a theme

`addTheme` takes a small light or dark palette; Paseo expands it into the full token set. Every color is a hex string.

```ts 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", }, }); ```

It appears under Settings → Appearance. A client that predates `addTheme` cannot evaluate the entry and reports `client.addTheme is not a function`; update the client. See `plugin-examples/catppuccin`.

## Hosts and trust

Plugins are installed per daemon and are trusted, unsandboxed code. Backend code can access files, processes, credentials, and network services on the daemon machine. Client contributions run inside the Paseo app. Do not install a plugin the user has not authorized or source code you have not inspected.

### Check the global switch before installing

Identify the target daemon and inspect its root `pluginsEnabled` value in `config.json`. For the local daemon, `paseo daemon status --json` reports its `home`; the file is `<home>/config.json`. Treat a missing field as `false`. Do not infer the global value from a plugin's `disabled` status, because an individual plugin can also be disabled.

If `pluginsEnabled` is already `true`, continue without asking the user to enable it.

If it is false or absent, stop and ask the user for explicit permission before editing or enabling anything. Include this warning in the request:

> Plugins are trusted, unsandboxed code. Backend plugin code can access your daemon machine, including files, processes, credentials, and network services. Client plugin code runs inside the Paseo app. May I enable plugins on this daemon?

Do not continue unless the user agrees. After permission:

1. Preserve the rest of `config.json` and set the root `pluginsEnabled` field to `true`. 2. Run `paseo reload --json` against that daemon. 3. Require `pluginsEnabled` in `appliedPaths`, or accept an empty `appliedPaths` only after re-reading the file and confirming the live plugin catalog is enabled. 4. Run `paseo plugin ls` and verify the intended plugin reaches `running` after installation.

If the user asks to disable the global switch, set `pluginsEnabled` to `false`, run `paseo reload --json`, and verify configured plugins report `disabled`.

Do not edit a local config when the target is a remote daemon. Perform the edit on the daemon machine, or ask the user to use **Settings → Plugins → Enable plugins**. `paseo reload --host <url>` reloads the remote daemon's own file but does not edit it.

When the same screen or sidebar item exists on several connected hosts, Paseo shows it once. The screen header has a host picker; a sidebar item uses the host of the screen on display, else the host last picked in one of the plugin's screens. The selected host owns the bundle, SDK calls, RPCs, and query cache. An offline selected host does not fall through to another host. Attachment sources stay scoped to the composer's host.

## Publishing a listing

Write `OVERVIEW.md` beside `paseo-plugin.json` for the plugin page inside Paseo. It helps someone decide whether to install your plugin; the install command is already at the top of that page. A README assumes a GitHub audience and carries installation instructions, technical details, and badges. Long, AI-generated READMEs make people read past that material to understand what a plugin does.

`OVERVIEW.md` is required to list your plugin in the registry. Commit it beside `paseo-plugin.json` in the source repository at the pinned commit. The registry resolves it relative to the manifest, under `pluginPath` for monorepos. Include it in the published npm package too; the scaffold's `files` list includes it. Replace the scaffold's guidance comment with useful facts before publishing.

The repository overview takes precedence over a registry import stopgap. Online validation fails when the pinned commit has no `OVERVIEW.md`, except for unchanged imported records that already carry `plugins/<owner>/<slug>.md` in the registry repository. Every version bump requires a repository overview and removes the stopgap in the same PR. A bump without the repository overview fails validation. README files do not supply the overview.

Author overviews and registry stopgaps follow the same content contract, in this order. Choose headings only when they help; length follows complexity. A theme needs one paragraph.

1. Explain what the plugin is and does in plain terms first. 2. Explain how it works only when that is not obvious. 3. Explain setup when needed: settings, accounts, tokens, providers, external tools, or other plugins. Include applicable daemon version and operating system requirements. Setup guidance is allowed; installation instructions are not. 4. Explain capabilities and settings worth understanding, what each option does, what the plugin reads or sends and where, permissions, and known limits.

Use sentence case and plain factual language, with no em dashes. Omit installation commands, badges, changelog, contributing or license sections, marketing, and unsupported claims. Avoid implementation filler such as empty cleanup functions, catalogs of theme-token fields, or lists of absent features. Keep only what helps someone choose the plugin.

If your plugin is an unchanged imported record, you can propose an author-written overview to replace the registry stopgap. Do not add import credit to your own `OVERVIEW.md`.

See [Your listing page](https://paseo.sh/docs/plugins/publishing.md#your-listing-page).

## Typecheck and manage

When editing a plugin, typecheck its source before install or reload:

```bash npm run typecheck paseo plugin install /absolute/path/to/plugin paseo plugin install /absolute/path/to/plugin --id another-runtime-id paseo plugin install npm:@acme/paseo-review paseo plugin install npm:@acme/[email protected] paseo plugin install github:owner/repository paseo plugin install github:owner/repository --ref main paseo plugin update my-plugin 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 ```

For npm, ensure npm is on the daemon's `PATH`; use that host's registry configuration and credentials. Install selectors choose content once; they do not pin updates. `install` and `add` are aliases. Follow the [publishing guide](https://paseo.sh/docs/plugins/publishing.md) for Paseo's package contents and preparation requirements; standard npm publishing commands apply.

Use `--host <url>` when managing a daemon other than the CLI default. A Git source that must install or generate something declares `build` in `paseo-plugin.json` as a list of argv arrays; Paseo runs them without a shell on install and update and keeps the old version if one fails. Plugin source edits require `paseo plugin reload`; config changes to the global switch require `paseo reload`. A failed plugin reload stays failed; inspect `paseo plugin ls` for the load error and `paseo plugin logs <id>` for subprocess output, fix the source, typecheck, and reload again. `remove` keeps local source directories and deletes managed Git/npm installations.

Do not restart the daemon to load source changes. Restarting it can kill the agent performing the work.

For an old mixed entry, follow the standalone [runtime-entry migration guide](https://paseo.sh/docs/plugins/migration) mechanically.

## Verify the outcome

After a change:

1. Run `npm run typecheck`. 2. Install or reload the exact runtime ID. 3. Run `paseo plugin ls` and require `running` with no error. 4. Confirm the contribution on the intended host. Open the Command Center with **⌘K** (macOS) or **Ctrl+K** (Windows/Linux). Type `/` in the composer for slash commands. For timeline work, run an agent turn that produces the source item and watch it while it streams, not only after it completes. For UI work, check a wide desktop window and a compact/mobile client, and switch theme to confirm text still uses `foreground` / `foregroundMuted`. 5. Exercise the changed action or RPC, including its error state.

Common failures:

- Missing sidebar item: wrong host, plugin not `running`, the item is hidden in Settings > Sidebar, or its component throws (a `SidebarRow` with an unknown Lucide name or unsafe SVG throws). - Unavailable client module: client bundles can use only the host-provided modules listed above. - RPC rejection: input or output failed its Zod schema, or the handler threw. Inspect `paseo plugin logs <id>` for handler output. - Plugin exits or reload fails: inspect `paseo plugin ls` for status and `paseo plugin logs <id>` for initialization, cleanup, or crash output. - Stale UI: source was edited without `paseo plugin reload <id>`. - Timeline item shows "Plugin timeline item unavailable": no renderer registered for that `kind` and `version`, the renderer schema rejected `data`, or the plugin is not running on that host. - Transformer has no effect: `query.itemType` does not match the source type, the transform returned `undefined`, or it threw and was skipped; check the app console for `[Plugins] Timeline transformer failed`. - Slash command not offered: name collides with a built-in or another plugin, the context is `agent` on a draft, or the composer has attachments. - Append rejected: the caller is not a plugin session, `data` exceeds 64 KiB, or the host predates `features.pluginTimelineItems`.

Intended uses

  • Use Paseo Plugin when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.