Plugin System

[cryppadotta]

Discuss:

https://github.com/paperclipai/paperclip/blob/master/doc/plugins/PLUGIN_SPEC.md
https://github.com/paperclipai/paperclip/blob/master/doc/plugins/ideas-from-opencode.md

[gsxdsm]

Generally this looks solid - two things top of mind:

1. It's not clear how the UI publishing (plugin UI->host UI) works - "schema driven view model" doesn't compute for me as to what that actually means in practice

2. Having a large api surface for functionality like file operations, git operations, process ops - feels like we're going to bloat the core - BUT I think its probably a fine tradeoff from a security and control POV. I would expect a plugin to hold logic on how to interface with git, etc - but I think this approach works to start and can always be opened up in the future

[cryppadotta]

@gsxdsm good feedback - yeah why bloat the core with plugin-specific calls.

The draft above was a rough draft so your concerns are totally worth addressing at this stage

[gsxdsm]

Will address in a revision -

For UI:
Plugins ship their own React UI.

• Plugin packages include a dist/ui/ directory with a built React bundle.
• The host defines extension slots (pages, tabs, widgets, sidebar entries) — designated mount points where plugin components appear.
• Plugin UI exports named components per slot (e.g. DashboardWidget, IssueDetailTab).
• The host mounts plugin components and passes a bridge object with hooks: usePluginData(key, params) → calls worker's getData RPC, usePluginAction(key) → calls worker's performAction RPC.
• Plugins own their rendering — they can use any React patterns, custom components, or third-party libraries.
• The host controls where components appear, enforces capability gates through the bridge, and publishes @paperclipai/plugin-ui with design tokens and shared components (MetricCard, DataTable, etc.) that plugins can optionally use.
• No iframe isolation in v1 (ES module loading for performance); iframe-based isolation deferred to Phase 3 for untrusted plugins.

[gsxdsm]

For API Surface:

Removed from core:

• Entire Section 19 (Workspace Service APIs) with all file, PTY, git, and process host APIs — replaced with a short "Local Tooling" section stating plugins handle these directly
• All workspace.* capabilities (~25 entries) from the capability model
• ctx.workspace from the SDK surface and example shape
• registerWorkspaceRuntime() from platform module surfaces
• "workspace service enforcement" from host responsibilities
• The tradeoff/future-path discussion (no longer needed since we're just not wrapping these)
• "direct filesystem access outside approved workspace services" from forbidden capabilities

New model:

• Plugins resolve workspace paths through ctx.projects (which provides workspace metadata like cwd, repoUrl, etc.)
• Plugins handle filesystem, git, PTY, and process operations directly using Node APIs or any libraries they choose
• The host stays lean — no parallel API surface for OS-level operations
• Phase 2 (workspace services) collapsed into Phase 1 since there's nothing extra to build on the host side
• All example plugin "hooks needed" sections trimmed to remove workspace capabilities, with notes that the plugin owns those operations directly

[gsxdsm]

Claude suggested plugins should be able to contribute tools that Agents can use. Adding to draft doc

[gsxdsm]

Recommendations here:
#273

https://github.com/gsxdsm/paperclip/blob/feature/plugins/doc/plugins/PLUGIN_SPEC.md

https://github.com/gsxdsm/paperclip/blob/feature/plugins/doc/plugins/ideas-from-opencode.md

[gsxdsm]

For plugin settings - where do we want the entry point in the UI, if any? There isn't really any paperclip-wide settings now - is that a philosophical choice we want to adhere to and keep all plugin settings out of the UI? or do we want to include? Right now I just have plugin settings next to company settings but its the wrong information architecture -

[aronprins]

Perhaps an icon next to the light/dark switcher for now for global plugin management, and then under company in the sidebar above the settings add "Plugins" where all plugins are visible and can be activated/deactivated on a per company basis.

[aronprins]

My preference/thoughts on plugins: global plugin installation but per "company" activation, similar to WP Multisite where all subsites have access to the plugins but can be activated on a per-site basis.