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 native surface, sidebar item, or workspace 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.
- Skill ID
- getpaseo/paseo/paseo-plugin
- Publisher
- getpaseo
- Repository
- paseo
- Installs
- 0
- Files
- 1
- Synced
- Sep 23, 2026
Open any RiverX project, open the Skills panel in the chat, and search for this identifier. The files are fetched from the source repository at install time.
getpaseo/paseo/paseo-pluginInstalls these files- SKILL.md
What this skill tells the agent
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.
User's request: $ARGUMENTS
Check current documentation
Fetch https://paseo.sh/llms.txt first. Select and fetch the current plugin Markdown pages from that index before changing a plugin:
- Plugin quickstart (browser page)
- Publishing: npm package contents, dependencies, Git preparation, and private registries.
- Plugin reference (browser page)
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 |
|---|---|---|---|
| Sidebar surface | addSurface + addSidebarItem | A full screen of plugin UI reachable from the sidebar | reference.md → Surfaces and sidebar items; plugin-examples/local-plugin |
| Workspace panel | addWorkspacePanel | UI that lives as a tab beside agents, terminals, files, and diffs; locations: ["explorer"] for the Explorer | reference.md → Workspace panels |
| 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 → Client 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 |
| Lifecycle events | server.on | Observe agent/workspace lifecycle, inspect ended turns, and answer permission requests | Lifecycle hooks |
| Creation and launch hooks | server.before | Change agent config, provider options, MCP servers, environment, or workspace isolation before the operation | 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 |
| Follow-ups, permissions, environment, provider switching, worktrees | lifecycle-actions |
| Inject MCP servers and change Codex sandbox/approval options | agent-configuration |
Create the project
Use an absolute path on the daemon machine. init writes files but does not install packages.
paseo plugin init /absolute/path/to/my-plugin
cd /absolute/path/to/my-plugin
npm installThe generated project contains:
my-plugin/
paseo-plugin.json
package.json
tsconfig.json
index.client.tsx
index.server.ts
client/greeting.tsx
server/greeting.ts
shared/greeting.tsThe manifest supplies the default install ID and supported Paseo versions:
{ "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.
Each runtime has its own optional entry. A plugin must have at least one. Both entries accept
More from getpaseo
Use this skill in a project
Open any RiverX project, search the Skills panel for getpaseo/paseo/paseo-plugin, and install it in one click.
