---
title: Plugin reference
description: Local plugin files, client and server runtimes, platform limits, contributions, RPCs, lifecycle, hosts, and CLI commands.
nav: Reference
order: 50
category: Plugins
---
# Plugin reference
Start with the [plugin quickstart](/docs/plugins) to create your first plugin.
Migrating an existing plugin? Follow the standalone [runtime-entry migration guide](/docs/plugins/migration).
Local plugins are directory sources installed into one Paseo daemon. A plugin can contribute:
- React Native screens and sidebar header and footer items to Paseo clients;
- workspace and agent panels opened as workspace tabs;
- [file panels](#file-panels) for viewing or editing matching files;
- 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 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.
## Connected hosts
`usePaseo().hosts` in a client surface and `context.paseo.hosts` in a server handler or lifecycle hook
use the same [SDK host API](/sdk/reference#clienthosts). They describe the selected daemon's saved
connections. Existing `useHosts()` and `getPaseoClient(serverId)` keep describing app-known hosts.
```ts
const remote = await context.paseo.hosts.client("srv_build_box");
try {
return await remote.workspaces.list();
} finally {
await remote.dispose();
}
```
A returned API owns its observations. Teardown of the plugin API also disposes derived scopes.
Keep remote calls inside the handler or lifecycle scope that owns them. Calling B does not forward
B's plugin lifecycle hooks to A. Registrations created by a routed plugin retain a source qualified
by the authenticated link and originating plugin.
## Project files
`paseo plugin init /absolute/path/to/my-plugin` creates:
```text
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`:
```json
{
"id": "my-plugin",
"description": "Reviews changes before merge",
"requirements": { "paseo": ">=0.8.0" }
}
```
| Field | Required | Behavior |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Yes | Default installation ID. |
| `name` | No | Non-empty display name for the registry, the website, your row in **Settings → Plugins**, and your settings header. Without it, Paseo shows the ID. |
| `icon` | No | Relative path to a PNG inside the plugin package. |
| `media` | No | Array of image or video paths inside the package, or HTTPS URLs. An empty array is valid. |
| `description` | No | Non-empty summary shown below the plugin name in **Settings → Plugins**. |
| `translations` | No | Listing text in other languages, read by the registry and ignored by Paseo. See [other languages](/docs/plugins/publishing#other-languages). |
| `requirements` | No | Supported Paseo versions, described below. |
| `build` | No | Preparation commands, described in the CLI reference. |
Paths are relative to `paseo-plugin.json`, use forward slashes, and cannot contain `..`
segments. Registry listings for visual plugins require an interface image even though `media` is
optional in the runtime manifest. See [icons and screenshots](/docs/plugins/publishing#icons-and-screenshots)
for accepted formats and listing requirements.
Paseo validates the references without opening local assets or fetching URLs.
Unknown top-level fields are ignored. Known fields still validate, and unknown keys inside
`requirements` are rejected so a misspelled constraint cannot silently skip a compatibility check.
Manifests using `name`, `icon`, or `media` require Paseo 0.11.0 or later; older daemons reject
these fields during installation.
### 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. Paseo 0.8 and later reject it with a link to the [migration guide](migration).
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 Paseo 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`.
A prerelease minimum such as `>=0.12.0-beta.4` therefore also admits `0.12.0-beta.3` through its stable core `0.12.0`. Use a different stable core when you need to exclude earlier builds of that core.
`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 preparation commands, or loading a plugin,
and checks again on startup, enable, and reload. A rejected 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 Paseo >=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` | Paseo 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](/docs/plugins/migration).
Plugin, screen, 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. Paseo 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 translations {#runtime-translations}
**Unreleased API.** Set `requirements.paseo` to the release that introduces these APIs before publishing your plugin. The [translation example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/translations) uses `>=0.12.1` provisionally; the introducing release has not been assigned.
Ship JSON resources with your client bundle. English (`en`) is required; other keys use canonical language tags such as `zh-CN`. Resources contain nested objects with string leaves. Other languages may omit keys, which fall back to English. Unknown keys, malformed resources, noncanonical locale tags, and mismatched interpolation placeholders are rejected when defining translations.
```ts
// client/messages.ts
import { defineTranslations } from "@getpaseo/plugin/client";
import en from "./locales/en.json";
import zhCN from "./locales/zh-CN.json";
export const messages = defineTranslations({ resources: { en, "zh-CN": zhCN } });
```
Enable `resolveJsonModule` in your plugin's `tsconfig.json`. Paseo bundles these imports locally; no network loader runs. For example, the resource pair can contain:
`client/locales/en.json`:
```json
{
"title": "Workspace notes",
"add": "Add note",
"notes_one": "{{count}} note",
"notes_other": "{{count}} notes"
}
```
`client/locales/zh-CN.json`:
```json
{
"title": "工作区笔记",
"add": "添加笔记",
"notes_other": "{{count}} 条笔记"
}
```
Call the plugin hook in React UI:
```tsx
import { useTranslation } from "@getpaseo/plugin/client";
import { Text } from "react-native";
import { messages } from "./messages";
function NoteCount({ count }: { count: number }) {
const { t, locale } = useTranslation(messages);
return {t("notes", { count })} ;
}
```
Use `messages.message(key, options?)` for persistent host-rendered labels:
```tsx
client.addScreen({
id: "notes",
title: messages.message("title"),
Component: Notes,
});
```
`PluginText` is `string | PluginMessage`. Message references work in screen titles (including title functions), settings and sidebar titles, workspace and file panel titles, Command Center titles, slash-command descriptions and argument hints, button titles and labels, nested menu titles, attachment-source titles/picker titles/search placeholders, and theme names. Existing literal strings remain valid. Keep IDs, slash-command names, icons, URLs, and command search keywords stable.
Descriptor types keep their existing string defaults. When explicitly annotating translated descriptors, use the text parameter, for example `PluginScreenContribution`. Inline registrations infer this automatically.
For transient text in callbacks, call `client.i18n.t(messages, "add")`; it reads the app's current language at invocation. `client.i18n.locale` and the hook's `locale` report the resolved app language even when a message falls back to English. Do not store the result of `t` as a persistent registration label.
Keys come from English. Plural base keys such as `notes` require a numeric `count`; i18next selects the locale's `_zero`, `_one`, `_two`, `_few`, `_many`, or `_other` form. Use `{{name}}` for named interpolation and pass `{ name: value }`. JSON string values are widened by TypeScript, so interpolation names from imported JSON are checked at runtime; inline literal resources also infer required interpolation names. i18next formatting syntax such as `{{amount, number}}` uses the resolved language's `Intl` formatter.
An explicit app language wins over the device language; System follows the app's supported-locale resolution. Separate connected apps have independent languages. Changing language updates mounted UI and host labels without reloading the plugin, resetting component state, or replacing its RPC/query cache. Modal and popover content receives the same installation context on web and native.
Return language-neutral structured RPC data and translate its presentation in the client. Keep user drafts, agent output, raw daemon errors, logs, and terminal text unchanged. Manifest listing translations and `OVERVIEW..md` are separate publication metadata; see [your listing page](publishing#your-listing-page).
## Runtime modules
Paseo 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/ui`. These rules include type imports and transitive
dependencies. `/client/host` is private to the app host; plugins cannot import it.
### Client runtime
Paseo provides these modules to client code:
| Module | Use it for |
| ---------------------------- | ------------------------------------------------------------------------------------------------- |
| `@getpaseo/plugin` | Shared data, `defineRpc`, `defineSettings`, `defineAttachmentSource`, `RpcInput`, and `RpcOutput` |
| `@getpaseo/plugin/client/ui` | Paseo UI components and UI hooks |
| `@getpaseo/plugin/client` | Client contribution contexts, `usePaseo`, `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 "" 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](https://lucide.dev/icons/), inline SVG, or a component; Paseo validates the icon and renders it. See [Icons](#icons).
### 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` | ``, `
`, ``, 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. Keep DOM globals out of cross-platform
components; do not add `/// ` or `"DOM"` to `lib`.
`layout.platform` carries the same value as React Native's `Platform.OS` for rendering decisions.
### Play audio
Call `client.playAudio({ base64, mimeType }): Promise` to play an audio file on the
current client (browser, Electron, iOS, or Android). Pass the base64 file returned by your
plugin RPC; no browser globals or platform checks are needed.
```ts
const audio = await client.rpc(renderSpeech, { text: "Your agent needs you" });
// renderSpeech returns { base64: string, mimeType: "audio/wav" }.
await client.playAudio(audio);
```
The promise resolves when playback finishes and rejects if the file is invalid, playback
fails, or the plugin unloads. Calls share Paseo's voice playback queue and play in order.
Unloading a plugin cancels its active and queued audio. Voice playback controls can also
interrupt that shared queue. Playback does not request microphone permission.
Use PCM WAV or MP3 for portable files. Other codecs depend on the client's decoder.
MIME parameters are accepted. Pass a complete audio file; raw PCM samples are not supported.
Browsers require user interaction before allowing sound; handle rejection and offer a
play button. The function plays on the device running the plugin client, not on the daemon,
and does not promise delivery while the app is suspended or closed.
### External links and workspace browsers
Use `ExternalLink` to open documentation outside Paseo:
```tsx
import { ExternalLink } from "@getpaseo/plugin/client/ui";
export function DocumentationLink() {
return Open documentation ;
}
```
The component has accessible link semantics and uses the same opener as
`openExternalUrl(url: string): Promise`:
```ts
import { openExternalUrl } from "@getpaseo/plugin/client";
export async function openDocumentation() {
await openExternalUrl("https://paseo.sh/docs");
}
```
Call the function directly from a user interaction so the browser permits a new tab.
| Platform | External links | `navigation.openBrowser` |
| ------------- | ---------------------------------- | ------------------------------------------------ |
| Electron | System browser | Available; creates a local workspace browser tab |
| Browser web | New tab with `noopener,noreferrer` | `undefined` |
| iOS / Android | OS URL handler | `undefined` |
#### ExternalLink props
| Prop | Required | Behavior / default |
| ------------------------------- | -------- | ------------------------------------------------------ |
| `href: string` | Yes | Absolute HTTP(S) destination |
| `children: ReactNode` | Yes | Link text or inline React Native content |
| `accessibilityLabel: string` | No | Overrides the accessible name derived from the content |
| `testID: string` | No | Test identifier; unset by default |
| `onError(error: unknown): void` | No | Receives opening errors; defaults to logging them |
#### Open a workspace browser
Use `navigation.openBrowser` from a surface or panel. Check availability before rendering
the action. This workspace panel chooses an external link on other platforms:
```tsx
import type { PluginWorkspacePanelProps } from "@getpaseo/plugin/client";
import { ExternalLink } from "@getpaseo/plugin/client/ui";
import { Pressable, Text } from "react-native";
export function DocumentationPanel({ navigation, workspaceId, theme }: PluginWorkspacePanelProps) {
const openBrowser = navigation?.openBrowser;
const url = "https://paseo.sh/docs";
if (!openBrowser) {
return Open documentation ;
}
return (
openBrowser({ url, workspaceId })}>
Open in workspace browser
);
}
```
`navigation.openBrowser({ url, workspaceId, serverId? }): void` creates and focuses a new tab.
It never opens externally as an automatic fallback.
| Option | Required | Behavior / default |
| --------------------- | -------- | ----------------------------------------------------------------- |
| `url: string` | Yes | Absolute HTTP(S) destination |
| `workspaceId: string` | Yes | Workspace already present in the target host's app workspace list |
| `serverId: string` | No | Defaults to the surface or panel's selected host |
To target another host, pass its ID with that host's workspace ID:
```ts
openBrowser({ url, workspaceId: remoteWorkspaceId, serverId: remoteServerId });
```
`serverId` selects workspace ownership. The page runs on your local desktop, including
for remote workspaces; `localhost` URLs refer to that desktop.
#### Errors and refusal
| Condition | Result |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| External URL is malformed or uses a non-HTTP(S) scheme | Ignored; `openExternalUrl` resolves without opening anything |
| OS opener fails | `openExternalUrl` rejects; `ExternalLink` calls `onError` or logs the error |
| Browser blocks a new external tab | Cannot be distinguished from a successful `noopener` open |
| In-app browser URL is malformed or uses a non-HTTP(S) scheme | Throws `Only absolute HTTP(S) URLs are supported.` before creating a tab |
| In-app browser workspace ID is empty | Throws `workspaceId is required.` before creating a tab |
| Target host/workspace is unknown or its workspace list has not loaded | Throws `Workspace is unavailable on the requested host.` before creating a tab |
Use the [settings API](#settings-screens) for typed host-scoped persistence across clients.
Use `openSettings`, `openScreen`, and `openPanel` for your own registered contributions.
### Server runtime
Paseo 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](/docs/plugins/providers) for direct and ACP implementations,
session lifecycle, option controls, 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 options are one record, `ProviderSessionConfig.providerOptions` on `session.open`. It
includes configured defaults and per-agent overrides; validate and apply it in your provider. Report
`controls` in `session.config` for the top-level keys that get a toggle or select in the composer,
with the values the session runs under `providerOptions`. A running-session change arrives as
`session.configure` with `changes.providerOptions`. See [Provider options](/docs/sdk/provider-options)
for configuration and merge semantics.
Host tools arrive as MCP servers in the complete
session config.
Paseo 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 for vendor behavior. See [Adapt an ACP agent](/docs/plugins/providers#adapt-an-acp-agent).
In `discover` and `configure`, call `context.request(method, params)` to send an ACP extension
request. The promise returns a JSON value or rejects with the agent's JSON-RPC error.
Use `config(state, context)` to return the configuration snapshot that Paseo displays.
Paseo calls this synchronous hook for initial, notification, and committed configuration snapshots.
Use `configure` to send changes to the agent.
`ProviderRegistration.icon` is a file path relative to the plugin directory, such as `icon.svg`.
It must resolve inside that directory to a regular file that follows the
[SVG icon rules](#svg-rules). Paseo reads and validates the file when the plugin starts; the string
is never inline SVG or a URL.
#### Provider installation
**Requires Paseo 0.17.** Older versions ignore `installation`.
`ProviderRegistration.installation` fills the **Installation** section of the provider's settings.
Every member is optional. Paseo hides the section when you declare neither `inspect` nor
`installUrl`. [Report installation and updates](/docs/plugins/providers#report-installation-and-updates)
has a complete example. Import the types from `@getpaseo/plugin/server/provider`.
```ts
interface ProviderInstallation {
installUrl?: string;
updateUrl?: string;
inspect?(context: ProviderInstallationContext): Promise;
checkForUpdates?(context: ProviderUpdateCheckContext): Promise;
update?(context: ProviderUpdateContext): Promise;
}
```
| Member | Called | Deadline | Answer kept |
| ----------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------ |
| `inspect` | When the provider list or a provider's page shows | 20 s | 30 s |
| `checkForUpdates` | After `inspect` answers `installed`, or without `inspect` | 25 s | 1 hour for `current` or `available`, else 30 s |
| `update` | When the user selects **Update**, one at a time per provider | None | Paseo reads both answers again after `succeeded` |
**Refresh** in the provider's settings skips the kept answers and clears a failed update. Paseo
never calls these members before a session or on a schedule. A deadline or a throw becomes an error that shows the message.
`installUrl` and `updateUrl` are `http` or `https` pages that Paseo opens in the browser. The
plugin fails to start when either is another kind of URL.
The context:
| Field | Type | Meaning |
| ------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `launch` | `ProviderInstallationLaunch \| undefined` | The launch a session would use, with `resolved`. Absent when the registration declares no `command`. |
| `signal` | `AbortSignal` | Aborts when Paseo stops waiting or the daemon stops. |
| `installedVersion` | `string \| undefined` | `checkForUpdates` only. The `version` `inspect` reported, as written. Absent when it reported none or you declare no `inspect`. |
| `report` | `(event: ProviderUpdateReport) => void` | `update` only. Shows `{ type: "stdout" \| "stderr" \| "message", text }` to the user in order. |
`ProviderInstallationLaunch` is `{ command, args, env, resolved }`. With `resolved: true`, `command`
is the executable's path. With `resolved: false`, Paseo did not find the executable and `command`
is the configured name.
Answers:
| Type | Values |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `ProviderInspection` | `{ status: "installed", version?: string }` or `{ status: "not_installed" }` |
| `ProviderUpdateCheck` | `{ status: "current" }`, `{ status: "available", versions?: string[], message?: string }`, or `{ status: "unknown", message?: string }` |
| `ProviderUpdateResult` | `{ status: "succeeded", message?: string }` or `{ status: "failed", message: string }` |
Paseo shows `version`, `versions` and `message` as written and does not parse or sort them. It
reuses a `current` or `available` answer for up to an hour while `inspect` reports the same
`version`. It keeps the last 65,536 characters of `report` output. An answer that does not match these
shapes is an error. **Update** appears once `inspect` reports the CLI installed and you declare
`update`, whatever `checkForUpdates` answers and whether you declare it; without `update`, Paseo
offers `updateUrl` on the same terms.
### Usage sources
**Requires Paseo 0.11.** Register a source from your server entry with
`server.registerUsageSource()`. Import its contract and helpers from
`@getpaseo/plugin/server/usage`.
A source that needs its plugin's provider command may set `provider` to that provider's ID.
The daemon supplies the resolved launch in `scope.launch` for global discovery and for that
provider's sessions. The launch includes the trusted process environment; keep it daemon-side and
use an opaque store locator as the input. It is absent when the provider is unavailable.
A source implements two calls:
```ts
interface UsageAccount {
key: string;
label?: string;
harness?: string;
input: JsonValue;
}
type UsageScope =
| { kind: "global"; launch?: ProviderLaunch }
| {
kind: "session";
provider: string;
model?: string;
env: Record;
launch?: ProviderLaunch;
};
interface UsageSourceRegistration {
id: string;
label: string;
icon?: string;
provider?: string;
input: ZodType;
discover(scope: UsageScope): Promise;
fetch(input: unknown): Promise;
}
type UsageReport =
| {
status: "available";
planLabel?: string;
windows: UsageWindow[];
balances?: UsageBalance[];
details?: UsageDetail[];
}
| { status: "unavailable"; problem: UsageProblem }
| { status: "error"; error: string };
type UsageProblem =
| { kind: "expired"; expiresAt: string; refreshedBy?: string }
| { kind: "rejected"; status: number; refreshedBy?: string }
| { kind: "no_quota"; detail: string };
```
Session discovery returns only the login that agent runs on. The agent popover uses only those
inputs; it never tries logins from global discovery or other agents. For any other provider,
return `[]`. Global discovery lists every account, including expired logins.
Resolve the session account from that session's launch environment. Return `[]` when no login exists.
Never scan default stores from session discovery or scan agents from global discovery. Discovery is a query, with no agent
lifecycle hooks. Closed agents have no session scope until resumed.
Inputs name credential stores; never put credentials in inputs or reports. Paseo validates each
input against your schema before calling `fetch()`. The same key in any scope is the same report;
fetches share a five-minute cache only when their ordered login inputs match. Each login fetch
has a 20-second deadline.
Built-in session routes:
| Source | Session | Login store |
| ---------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Claude | `claude` | `CLAUDE_CONFIG_DIR`, or the default; on macOS, the directory's Keychain entry takes precedence |
| Claude | `pi`, `omp` with `anthropic/…` model | That harness's Anthropic login store |
| Codex | `codex` | `CODEX_HOME/auth.json`, or the default |
| Codex | `pi`, `opencode`, `omp` with `openai/…` model | That harness's OpenAI login store |
| Cursor | `cursor` | cursor-agent's `auth.json` for that session's `XDG_CONFIG_HOME`, `APPDATA`, or home directory |
| Muse | `muse` | That session's own Muse launch/config |
| Other built-in sources | Any | No session discovery |
Claude excludes Bedrock, Vertex, and foreign `ANTHROPIC_BASE_URL` sessions. Codex excludes sessions
with `OPENAI_BASE_URL` set. Cursor excludes sessions that authenticate with `CURSOR_API_KEY` or
`CURSOR_AUTH_TOKEN`, and macOS sessions that keep the login in the Keychain, the default unless
`AGENT_CLI_CREDENTIAL_STORE=file`.
Use a stable account key: 1–128 characters from `[A-Za-z0-9._-]`. It identifies the account or
organization whose quota is metered and survives token rotation. Never use a credential or raw
email as the key. Use `hashAccountKey()` for sensitive stable identities or a store locator when
account metadata is unavailable. Labels can name accounts without becoming their identity.
Return logins in preference order and set `harness` to the owning harness's display name, such as
Codex, OpenCode, Pi, or OMP. The daemon treats inputs as opaque and never derives labels from them.
The host-wide Usage modal groups logins with the same key into one account card and tries them
concurrently, preferring the discovery order when selecting a result. If any login returns
`available`, it shows usage with no errors. If all fail, it shows
every login's error on a separate line with its harness label and its own remedy.
Discovery failures are logged by the daemon and produce no card.
Window names must come from provider data: an explicit duration, a named API field such as
`five_hour` or `weekly`, or the provider's own period name. Response slots and reset countdowns
do not establish duration. When the provider omits it, use a neutral name such as “Rolling” or
“Primary limit” and explain the missing metadata next to the adapter.
For numeric durations, use `windowFromReportedDuration()` from
`@getpaseo/plugin/server/usage` (Paseo 0.11+). Pass the reported seconds or `null`, a neutral
`unknown` identity and name, and an optional stable quota `scope`. The helper derives the ID,
label, and short label together; it accepts no duration-label override. For named API periods,
use `windowFromUsedPct()` with names justified by that field.
A window ID identifies a quota scope and period, never its response position, utilization, or
reset instant. Scope model-specific quotas by the provider's stable feature ID, falling back to
the reported limit name when no ID exists. Preserve IDs across slot moves and display-name
changes. Do not alias an old ambiguous ID to a different period: saved pins match source and
window IDs across all accounts, so users must select the corrected window again.
`summary: true` selects source defaults until the user customizes pins. The app computes one
effective selection for cards, the sidebar, and toggles. The first edit snapshots those defaults;
an explicit empty selection stays empty.
Re-read the selected store in `fetch()` so the CLI's token rotations take effect. If you discover
a specific account, pass its identity in the input and verify it before returning usage.
Throw if the store disappears or the login changes accounts. The next discovery updates the card.
Only the CLI should redeem its refresh tokens or write its credential stores.
Use `unavailable(problem)` to explain why an existing login cannot supply quota. It requires a
problem; there is no zero-argument form. `expiresAt` is an ISO timestamp. A rejected login carries
the upstream HTTP status. `refreshedBy` is a CLI name, such as `claude`, `codex`, `opencode`, `omp`, or
`pi`. Paseo owns the remedy sentence. Do not put instructions or user-facing sentences in that
field. For `no_quota`, `detail` is displayed verbatim.
```ts
import { z } from "zod";
import type { PluginServerContext } from "@getpaseo/plugin/server";
import { hashAccountKey, unavailable } from "@getpaseo/plugin/server/usage";
import { findLoginStores, readLogin, readQuota } from "./server/logins";
const input = z.object({ path: z.string() }).strict();
export default function contribute(server: PluginServerContext) {
server.registerUsageSource({
id: "example-usage",
label: "Example",
icon: "icon.svg",
input,
discover: async () =>
(await findLoginStores()).map((path) => ({
key: hashAccountKey(path),
input: { path },
})),
fetch: async (value) => {
const { path } = input.parse(value);
const login = await readLogin(path);
if (login.expiresAt <= Date.now())
return unavailable({
kind: "expired",
expiresAt: new Date(login.expiresAt).toISOString(),
refreshedBy: "example",
});
return readQuota(login);
},
});
return () => {};
}
```
Built-in Claude discovery prefers the macOS Keychain login and uses the Claude Code credential
file only when Keychain is empty. `CLAUDE_CONFIG_DIR` selects that file's directory. Fresh tokens
use the OAuth profile's account and organization IDs; expired or rejected profiles use a locator
hash. Codex prefers Codex CLI, OpenCode, Pi, then OMP and groups by the ChatGPT account ID from stored
metadata or JWT claims. Pi and OMP logins remain discoverable when expired. OMP requires
`node:sqlite`.
`usage.list_reports` discovers accounts for the requested agent. A host-wide request discovers
the defaults and revisits the agents whose usage Paseo has already queried. A request with report
IDs fetches known reports using their existing discovery inputs. Reports are cached for five minutes.
Set `forceRefresh` to bypass that cache. Entries carry `id`, `account.label`, and `fetchedAt`.
Failed accounts also carry optional
`loginErrors` entries with `harness` and each login's failed `report`. Clients gate the feature
on `server_info.features.usageSources`. The older `provider.usage.list` RPC maps the same reports
for 0.10 clients and renders problems into its `error` string.
The source icon is a file path with the same rules as a provider icon.
## Worktree managers {#worktree-managers}
**Requires Paseo 0.16.** Register a worktree manager from `index.server.ts` with
`server.registerWorktreeManager()` when an external tool such as Worktrunk should own creating,
removing, and restoring Git worktrees instead of Paseo running `git worktree add` and
`git worktree remove` directly.
```ts
import { execCommand, type PluginServerContext } from "@getpaseo/plugin/server";
export default function contribute(server: PluginServerContext) {
return server.registerWorktreeManager({
async create(request, { signal }) {
if (request.kind !== "branch-off") return;
const { stdout } = await execCommand(
"wt",
[
"-C",
request.repoRoot,
"switch",
"--create",
request.branch,
"--base",
request.startPoint ?? request.baseRef,
"--no-cd",
request.untrusted ? "--no-hooks" : "--yes",
"--format=json",
],
{ signal },
);
const { path } = JSON.parse(stdout) as { path: string };
return { type: "created", path };
},
async remove({ repoRoot, path, force, untrusted }, { signal }) {
const skipHooks = untrusted || repoRoot === null;
await execCommand(
"wt",
[
"-C",
repoRoot ?? path,
"remove",
"--foreground",
"--no-delete-branch",
skipHooks ? "--no-hooks" : "--yes",
...(force ? ["--force"] : []),
path,
],
{ signal },
);
return { type: "removed" };
},
async restore({ repoRoot, path, target, untrusted }, { signal }) {
if (target.type !== "branch") return;
const { stdout } = await execCommand(
"wt",
[
"-C",
repoRoot,
"switch",
target.branch,
"--path",
path,
"--no-cd",
untrusted ? "--no-hooks" : "--yes",
"--format=json",
],
{ signal },
);
const { path: restoredPath } = JSON.parse(stdout) as { path: string };
return { type: "restored", path: restoredPath };
},
});
}
```
- **Create** runs after all `worktree.create.before` hooks and before `worktree.create.after`, with a
120-second timeout. Return `{ type: "created", path }` to claim creation, or `undefined` to decline
so the next manager or Paseo's built-in Git checkout runs. For branch-off, Paseo resolves
`baseRef` and refreshes a remote-tracking starting ref before calling the manager, using the
cached ref if the fetch fails. When `request.untrusted` is `true` (for
example, a fork change request), skip repository-defined hooks. Paseo verifies that `path` is a
safe, newly created Git worktree of the same repository on a named branch, then records the
checked-out `HEAD` branch (managers may normalize or uniquely name the branch, and should create a
new branch for `branch-off`), writes comparison-base metadata, and seeds `paseo.json`. Paseo uses the
returned path to roll back a failed adoption or later creation step. If the callback throws or
its signal aborts before it returns, the manager is responsible for cleaning up any worktree it
created. First-agent branch auto-rename is skipped for manager-created worktrees.
- **Remove** is optional and runs on workspace archive and creation rollback, after Paseo runs
`paseo.json` teardown and saves `refs/paseo/kept-commits/` for restore. Return
`{ type: "removed" }` after removing the directory, or `undefined` to fall back to Git. When
`untrusted` is `true` (for example, a fork change request) or `repoRoot` is `null`, skip
repository-defined hooks and run against `repoRoot` when available. Paseo routes removal to the
plugin that created the worktree, falling back to Git when that plugin is disabled or uninstalled.
- **Restore** is optional and runs when unarchiving a workspace whose worktree directory was deleted.
It receives the recorded `path` that the recreated worktree must occupy, `target` (`branch`,
`commit`, or `from-base`), and `untrusted`. Return `{ type: "restored", path }` or `undefined` to
fall back to Git. Paseo verifies the checkout matches the requested branch, detached commit, or
new branch at the requested base commit. The same cleanup rules apply as for create. When
`restore` falls back to Git, Paseo clears the workspace's manager ownership
so subsequent archives also use Git.
See the complete [worktrunk example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/worktrunk).
## 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 Paseo removes remaining registrations.
```ts
import type { PluginClientContext } from "@getpaseo/plugin/client";
import { Main } from "./client/main";
export default function contribute(client: PluginClientContext) {
client.addScreen({ id: "main", title: "My plugin", Component: Main });
return () => {};
}
```
Cleanup can be async. Release timers, watchers, sockets, and other resources created by the plugin. Reload, disable, and removal dispose the affected installation. Stopping a server plugin also closes its daemon session and stops its subprocess. Client installations follow [Hosts and lifecycle](#hosts-and-lifecycle), including retention during a temporary disconnect.
## Lifecycle hooks
Register async handlers with `server.addHook(name, handler)`. See [Hooks](/docs/plugins/hooks) for names, payloads, ordering, errors, and complete examples.
## Sidebar views
`addSidebarView({ id, title, description?, Component })` registers an optional replacement for the
sidebar content region. It returns cleanup. The user selects one view in Settings > Sidebar;
registration does not activate it. See [Build a sidebar view](sidebar-views.md) for the props,
ref-based queries and actions, device state and theme tokens.
## Screens and sidebar items
A screen is a full page of plugin UI. A sidebar item is a component Paseo renders in the sidebar
header or footer; it decides what a press does. Register the screen, then an item that opens it:
`client/main.tsx`:
```tsx
import type { PluginScreenProps } from "@getpaseo/plugin/client";
import { useMemo } from "react";
import { Text, View } from "react-native";
export function Main({ theme, host, layout }: PluginScreenProps) {
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 (
{host.label}
{layout.platform}
);
}
```
`index.client.tsx`:
```tsx
import type { PluginClientContext, PluginSidebarItemProps } from "@getpaseo/plugin/client";
import { SidebarRow } from "@getpaseo/plugin/client/ui";
import { Main } from "./client/main";
function MainItem({ currentScreen, openScreen }: PluginSidebarItemProps) {
return (
openScreen({ screenId: "main" })}
/>
);
}
export default function contribute(client: PluginClientContext) {
client.addScreen({ id: "main", title: "My plugin", Component: Main });
client.addSidebarHeaderItem({ id: "main", title: "My plugin", Component: MainItem });
return () => {};
}
```
`PluginScreenProps` 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. |
| `params` | The params the screen was opened with, as string keys and values. `{}` when none. |
| `navigation` | Optional client navigation. `openAgent({ agentId, serverId? })` and `openWorkspace({ workspaceId, serverId? })` open targets on `serverId`, or on the selected host when omitted. `openBrowser({ url, workspaceId, serverId? })` is available only on Electron; see [links and browsers](#external-links-and-workspace-browsers). |
Paseo owns the route, header, close action, host picker, error boundary, and query client. The plugin owns the screen body.
`addScreen({ id, title, Component })` registers a screen. `title` is the screen header's title: a
[display text](#runtime-translations), or a function that takes the screen's params and returns
display text. The function runs again when params or language change. Invalid or empty literal
titles are rejected. A title function that throws or resolves to an empty string shows the screen
ID instead; the screen still renders.
`openScreen({ screenId, params })` opens a screen with params, such as the bot a bot screen shows.
Params live in the screen's URL query, so a reload, back and forward, and a link to the screen keep
them. Any string key works; values must be strings, and anything else throws. Opening the same
screen with other params shows the new params.
### Sidebar items
`addSidebarHeaderItem` adds a row to the list at the top of the sidebar. `addSidebarFooterItem`
adds a row to the footer, between **Add project** and the footer's icon row. The icon row is fixed;
plugins can't add to it. Both take `{ id, title, Component }`. `title` labels the item in
Settings > Sidebar, where users reorder and hide items, and is the default label and accessibility
label of `SidebarRow`. Settings shows a generic plugin icon for these items; a row from the
deprecated `addSidebarItem` keeps its registered icon.
With the plugin on several hosts, an item renders from the host of the screen the app shows. Off a
host's screens, it uses the host last picked in one of the plugin's screens or last opened from one
of its items, else the first host.
`Component` receives `PluginSidebarItemProps`:
| Field | Meaning |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| `theme`, `host`, `layout` | As in `PluginScreenProps`. |
| `currentScreen` | `{ screenId, params }` of this plugin's screen open on the item's host, or `null`. |
| `openScreen(input)` | Opens one of this plugin's screens: `{ screenId, params? }`. Unknown screen IDs throw. |
| `openPopover(Content)` | Opens `Content` anchored to the pressed row on wide layouts and as a bottom sheet on compact. |
`Content` receives `theme`, `host`, `layout`, `close()`, and `openScreen(input)`. Opening a screen
closes the popover.
Render the item with the sidebar kit from `@getpaseo/plugin/client/ui`:
| Component | Props and behavior |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SidebarRow` | Required `onPress`; optional `icon` (any [icon](#icons) form), `label`, `active`, `trailing`, `id`. A full-width row. `trailing` renders beside the row's pressable, so a button in it presses on its own; a press elsewhere in it presses the row. `id` tells rows of one item apart in test IDs. |
| `SidebarSeparator` | No props. The sidebar's separator line, between groups of rows. |
A popover anchors to the row that was pressed, whether the press landed on the row or on its
`trailing` content, so a per-row "More" button opens its popover next to its own row.
```tsx
import type { PluginSidebarItemProps, PluginPopoverProps } from "@getpaseo/plugin/client";
import { SidebarRow } from "@getpaseo/plugin/client/ui";
import { Pressable, Text } from "react-native";
function SyncDetails({ theme, close, openScreen }: PluginPopoverProps) {
return (
openScreen({ screenId: "sync" })}>
Open sync history
);
}
function SyncItem({ openPopover }: PluginSidebarItemProps) {
return openPopover(SyncDetails)} />;
}
client.addSidebarFooterItem({ id: "sync", title: "Sync", Component: SyncItem });
```
An item that throws renders nothing; the rest of the sidebar keeps working.
#### Several rows in one item
An item's `Component` may return a fragment, an array, or `null`, so one item can render a list
that changes at runtime. Settings lists the item once, and it moves and hides as one block. This
item shows a row per bot and opens the bot's screen with its ID as a param:
```tsx
import type {
PluginClientContext,
PluginScreenProps,
PluginSidebarItemProps,
} from "@getpaseo/plugin/client";
import { SidebarRow, SidebarSeparator } from "@getpaseo/plugin/client/ui";
import { Text } from "react-native";
import { botName, useBots } from "./client/bots";
function BotScreen({ theme, params }: PluginScreenProps) {
return Bot {params.botId} ;
}
function BotsItem({ currentScreen, openScreen }: PluginSidebarItemProps) {
const bots = useBots();
const openBotId = currentScreen?.screenId === "bot" ? currentScreen.params.botId : null;
return (
<>
{bots.map((bot) => (
openScreen({ screenId: "bot", params: { botId: bot.id } })}
/>
))}
>
);
}
export default function contribute(client: PluginClientContext) {
client.addScreen({
id: "bot",
title: (params) => botName(params.botId) ?? "Bot",
Component: BotScreen,
});
client.addSidebarHeaderItem({ id: "bots", title: "Bots", Component: BotsItem });
return () => {};
}
```
#### Add and remove items at runtime
`addSidebarHeaderItem` and `addSidebarFooterItem` work after the entry returns. Each returns a
remover; the item appears and disappears without a reload:
```tsx
let removeAlerts: (() => void) | null = null;
function showAlerts(client: PluginClientContext) {
removeAlerts ??= client.addSidebarFooterItem({
id: "alerts",
title: "Alerts",
Component: AlertsItem,
});
}
function hideAlerts() {
removeAlerts?.();
removeAlerts = null;
}
```
### Workspace row badge items
`addWorkspaceRowBadgeItem({ id, title, icon, Component })` adds an item to the line under each workspace
title in the sidebar, after the row's own items (host, pull request, checks, services, labels).
`title` and `icon` label the item's toggle in the sidebar's **Show** menu, in a separate plugin group
below a separator. Items start visible.
`Component` renders once per workspace row on the plugin's host and receives
`PluginWorkspaceRowBadgeItemProps`: `theme`, `host`, `layout`, and `workspaceId`. Render
`WorkspaceRowBadge` from `@getpaseo/plugin/client/ui`, or `null` when there is nothing to say about
the workspace:
| Prop | Meaning |
| -------------------- | ------------------------------------------------------------------------------ |
| `icon` | Optional. Any [icon](#icons) form, drawn at the line's glyph size. |
| `label` | Optional. A short word. A badge with neither `icon` nor `label` draws nothing. |
| `tone` | `"muted"` (default), `"success"`, `"warning"`, `"danger"`, or `"info"`. |
| `accessibilityLabel` | Defaults to `label`, then the item's `title`. |
The line adds no separator around your badges, and returning `null` leaves no gap. Render as many
badges as you like. Every row
renders the component, so share one query across rows instead of fetching per workspace: the
plugin's React Query client is shared by all of its components on a host.
```tsx
import type { PluginWorkspaceRowBadgeItemProps } from "@getpaseo/plugin/client";
import { useRpc } from "@getpaseo/plugin/client";
import { WorkspaceRowBadge } from "@getpaseo/plugin/client/ui";
import { useQuery } from "@tanstack/react-query";
function ReviewState({ workspaceId }: PluginWorkspaceRowBadgeItemProps) {
const list = useRpc(reviewStates);
const { data } = useQuery({
queryKey: ["review-states"],
queryFn: () => list({}),
refetchInterval: 5000,
});
const state = data?.[workspaceId];
if (!state) return null;
return ;
}
client.addWorkspaceRowBadgeItem({
id: "review",
title: "Review",
icon: "Eye",
Component: ReviewState,
});
```
Apps older than this API have no `addWorkspaceRowBadgeItem`; check for it before calling.
See the [workspace row badges example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/workspace-row-badges).
## Host UI
Import Paseo-owned UI from `@getpaseo/plugin/client/ui` in client code. This example
opens a controlled modal, renders a host icon, and confirms the action with a toast:
```tsx
import type { PluginSurfaceProps } from "@getpaseo/plugin/client";
import { Icon, Modal, useToast } from "@getpaseo/plugin/client/ui";
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 (
setOpen(true)}>
Edit issue
}
open={open}
onOpenChange={setOpen}
>
Save
);
}
```
### Markdown
Import `Markdown` from `@getpaseo/plugin/client/ui` to render a string with Paseo's
Markdown presentation on web, iOS, and Android:
```tsx
import { Markdown } from "@getpaseo/plugin/client/ui";
{"## Review\n\nThe checks **passed**."} ;
```
`children` is the only prop and must be a string. Updating it renders the new content
immediately; an empty string renders nothing. The host supplies theme, text selection,
code blocks, tables, diagrams, and link handling. Workspace file links and images use
workspace context when the containing surface supplies it.
The component adds no page padding or scroll container. Use a surrounding layout or
scroll view when needed. Fetching content and showing loading or error states belong
to your plugin.
### 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 | Default | Behavior |
| ----------------------- | ---------------------- | ------------------ | --------------------------------------------------------------------------------- |
| `children` | `ReactNode` | Required | Body content below the header. |
| `style` | `StyleProp` | — | Styles the full body viewport, including empty space. Use for backgrounds. |
| `contentContainerStyle` | `StyleProp` | 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. `usePaseo`, `useRpc`, `useWorkspace`, and
`useAgent` work inside them.
### Scrolling
Import `ScrollView` and `FlatList` from `@getpaseo/plugin/client/ui` when content can appear in a
Paseo 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.
```tsx
import { FlatList, Modal } from "@getpaseo/plugin/client/ui";
import { Text } from "react-native";
// Inside your controlled Modal:
item.id}
renderItem={({ item }) => (
{item.title}
)}
/>
;
```
For horizontal tabs, place `… ` inside the
default `Modal.Content`. Keep the content's vertical scrolling on the host.
### Copy and paste
`copyText(text): Promise` 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.
```tsx
import { copyText, useToast } from "@getpaseo/plugin/client/ui";
// 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 ``
for long-press selection and OS Copy. Import `TextInput` from `@getpaseo/plugin/client/ui` 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](https://github.com/getpaseo/paseo/tree/main/plugin-examples/modal-ui)
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
Every contribution `icon` field takes one of three forms, typed `PluginIcon` in
`@getpaseo/plugin/client`:
| Form | Example | Use it for |
| ----------- | --------------------------- | --------------------------------------------------- |
| Lucide name | `icon: "Scan"` | Any [Lucide icon](https://lucide.dev/icons/). |
| Inline SVG | `icon: { svg: reviewIcon }` | A brand mark or an icon Lucide does not have. |
| Component | `icon: ReviewBadge` | An icon that changes with state, such as a counter. |
Attachment sources take a Lucide name or inline SVG (`PluginSerializableIcon`), because each
attached item stores its source's icon.
Paseo validates the icon when the contribution registers. An unknown Lucide name or an SVG that
breaks a rule fails the plugin with the reason:
```text
Workspace panel review has an invalid icon: script elements are not allowed
```
Paseo draws inline SVG at the surface's icon size and passes the surface's icon color as
`currentColor`. Paint with `currentColor` to follow the theme; fixed fills keep their colors.
A component receives `PluginIconProps`, `{ size, color }`, and renders within that size. Header
buttons and composer pills pass [`PluginButtonIconProps`](#custom-icons-and-popover-content).
#### SVG rules
Inline SVG, provider icons, and usage-source icons follow the same rules:
- One `` document, no larger than 64 KiB.
- No `