colonelpanic8/dotfiles/paseo-plugin

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.

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 install

The generated project contains:

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:

{ "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 .ts or .tsx; use .tsx when an entry imports components.

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:

// index.client.tsx
import type { PluginClientContext } from "@getpaseo/plugin/client";
export default function contribute(client: PluginClientContext) {
  // Register components and client callbacks here.
  return () => {};
}

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

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