From f510b3edb7acc76e5d0be41fab43971f1ff1a261 Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Wed, 18 Nov 2026 12:05:21 +0700 Subject: [PATCH] Tell plugin agents to develop in a directory plugin, never a Git or npm installation (#10061) * Tell plugin agents to develop in a directory plugin, never a Git or npm installation paseo plugin update replaces a Git or npm installation and remove deletes it, so edits and commits made in Paseo's managed copy are lost. The paseo-plugin skill now says to clone the source outside the daemon home and install that directory, and to move any work out of a managed copy before update or remove. Refs #7904 * Rewrite the plugin development guidance as plain steps * Keep settings, runtime ID, and build output when moving a plugin to a local folder --- skills/paseo-plugin/SKILL.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/skills/paseo-plugin/SKILL.md b/skills/paseo-plugin/SKILL.md index 53a301eeb6..85030768d9 100644 --- a/skills/paseo-plugin/SKILL.md +++ b/skills/paseo-plugin/SKILL.md @@ -52,6 +52,36 @@ Pick the contribution that matches the request. Each row names the registration, | 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 ` 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 ` and read the SOURCE column. A +`git:` source, an `npm:` source, or a registry source such as `/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 `:`, 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 ` also + deletes the saved settings of the plugin. +6. Run `paseo plugin remove `. +7. Run `paseo plugin install /absolute/path/to/plugin-folder --id ` to keep the runtime ID. +8. Edit the plugin folder, and run `paseo plugin reload ` 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.