doc/plugins/ideas-from-opencode.md
Status: design report, not a V1 commitment
Paperclip V1 explicitly excludes a plugin framework in doc/SPEC-implementation.md, but the long-horizon spec says the architecture should leave room for extensions. This report studies the opencode plugin system and translates the useful patterns into a Paperclip-shaped design.
Assumption for this document: Paperclip is a single-tenant operator-controlled instance. Plugin installation should therefore be global across the instance. "Companies" are still first-class Paperclip objects, but they are organizational records, not tenant-isolation boundaries for plugin trust or installation.
opencode has a real plugin system already. It is intentionally low-friction:
That model works well for a local coding tool. It should not be copied literally into Paperclip.
The main conclusion is:
opencode's typed SDK, deterministic loading, low authoring friction, and clear extension surfaces.opencode's trust model, project-local plugin loading, "override by name collision" behavior, or arbitrary in-process mutation hooks for core business logic.If Paperclip does this well, the examples you listed become straightforward:
I cloned anomalyco/opencode and reviewed commit:
a965a062595403a8e0083e85770315d5dc9628abPrimary files reviewed:
https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/plugin/src/index.tshttps://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/plugin/src/tool.tshttps://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/plugin/index.tshttps://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/config/config.tshttps://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/tool/registry.tshttps://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/provider/auth.tshttps://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/web/src/content/docs/plugins.mdxhttps://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/web/src/content/docs/custom-tools.mdxhttps://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/web/src/content/docs/ecosystem.mdxRelevant Paperclip files reviewed for current extension seams:
opencode exposes a small package, @opencode-ai/plugin, with a typed Plugin function and a typed tool() helper.
Core shape:
Hooks objectThe plugin init context includes:
That is important: opencode gives plugins rich runtime power immediately, not a narrow capability API.
The hook set is broad. It includes:
The implementation pattern is very simple:
output objectoutputThis is elegant and easy to extend.
It is also extremely powerful. A plugin can change auth headers, model params, permission answers, tool inputs, tool descriptions, and shell environment.
opencode supports two plugin sources:
Local directories:
~/.config/opencode/plugins/.opencode/plugins/Npm plugins:
plugin: []Load order is deterministic and documented:
Important details:
This gives opencode a real precedence model rather than "whatever loaded last by accident."
For local config/plugin directories, opencode will:
package.json exists@opencode-ai/pluginbun installThat lets local plugins and local custom tools import dependencies.
This is excellent for local developer ergonomics.
It is not a safe default for an operator-controlled control plane server.
Plugin load failures do not hard-crash the runtime by default.
Instead, opencode:
That is a good operational pattern. One bad plugin should not brick the entire product unless the operator has explicitly configured it as required.
opencode has two ways to add tools:
hook.tool.opencode/tools/ or global tools directoriesThe tool API is strong:
tool.definition hookThe most aggressive part of the design:
That is very powerful for a local coding assistant. It is too dangerous for Paperclip core actions.
However, the concept of plugins contributing agent-usable tools is very valuable for Paperclip — as long as plugin tools are namespaced (cannot shadow core tools) and capability-gated.
opencode allows plugins to register auth methods for providers.
A plugin can contribute:
This is a strong pattern worth copying. Integrations often need custom auth UX and token handling.
The ecosystem page is the best proof that the model is working in practice. Community plugins already cover:
That validates the main thesis: a simple typed plugin API can create real ecosystem velocity.
This is one of the best parts of the design.
Paperclip should absolutely do this.
opencode is explicit about:
Paperclip should copy this discipline.
A plugin author does not have to learn a giant framework.
That simplicity matters.
The tool() helper is excellent:
Paperclip should adopt this style for plugin actions, automations, and UI schemas.
opencode uses the same hook system for internal and external plugin-style behavior in several places.
That reduces special cases.
Paperclip can benefit from that with adapters, secret backends, storage providers, and connector modules.
opencode did not design a giant marketplace platform first.
It added concrete extension points that real features needed.
That is the correct mindset for Paperclip too.
opencode is basically a local agent runtime, so unsandboxed plugin execution is acceptable for its audience.
Paperclip is a control plane for an operator-managed instance with company objects. The risk profile is different:
Default third-party plugins should not run with unrestricted in-process access to server memory, DB handles, and secrets.
opencode has project-local plugin folders because the tool is centered around a codebase.
Paperclip is not project-scoped. It is instance-scoped. The comparable unit is:
Paperclip should not auto-load arbitrary code from a workspace repo like .paperclip/plugins or project directories.
Hooks like:
permission.asktool.execute.beforechat.headersshell.envmake sense in opencode.
For Paperclip, equivalent hooks into:
would be a mistake.
Core invariants should stay in core code, not become hook-rewritable.
Allowing a plugin to replace a built-in tool by name is useful in a local agent product.
Paperclip should not allow plugins to silently replace:
Extension should be additive or explicitly delegated, never accidental shadowing.
opencode's "install dependencies at startup" flow is ergonomic.
For Paperclip it would be risky because it combines:
inside the control-plane server startup path.
Paperclip should require an explicit operator install step.
The products are solving different problems.
| Topic | OpenCode | Paperclip |
|---|---|---|
| Primary unit | local project/worktree | single-tenant operator instance with company objects |
| Trust assumption | local power user on own machine | operator managing one trusted Paperclip instance |
| Failure blast radius | local session/runtime | entire company control plane |
| Extension style | mutate runtime behavior freely | preserve governance and auditability |
| UI model | local app can load local behavior | board UI must stay coherent and safe |
| Security model | host-trusted local plugins | needs capability boundaries and auditability |
That means Paperclip should borrow the good ideas from opencode but use a stricter architecture.
Paperclip has several extension-like seams already:
This is good news. Paperclip does not need to invent extensibility from scratch. It needs to unify and harden existing seams.
Do not create one giant hooks object for everything.
Use distinct plugin classes with different trust models.
| Extension class | Examples | Runtime model | Trust level | Why |
|---|---|---|---|---|
| Platform module | agent adapters, storage providers, secret providers, run-log backends | in-process | highly trusted | tight integration, performance, low-level APIs |
| Connector plugin | Linear, GitHub Issues, Grafana, Stripe | out-of-process worker or sidecar | medium | external sync, safer isolation, clearer failure boundary |
| Workspace plugin | file browser, terminal, git workflow, child process/server tracking | out-of-process, direct OS access | medium | resolves workspace paths from host, owns filesystem/git/PTY/process logic directly |
| UI contribution | dashboard widgets, settings forms, company panels | plugin-shipped React bundles in host extension slots via bridge | medium | plugins own their rendering; host controls slot placement and bridge access |
| Automation plugin | alerts, schedulers, sync jobs, webhook processors | out-of-process | medium | event-driven automation is a natural plugin fit |
This split is the most important design recommendation in this report.
Paperclip already has this pattern implicitly:
Keep that separation.
I would formalize it like this:
module means trusted code loaded by the host for low-level runtime servicesplugin means integration code that talks to Paperclip through a typed plugin protocol and capability modelThis avoids trying to force Stripe, a PTY terminal, and a new agent adapter into the same abstraction.
For third-party plugins, the primary API should be:
Do not make third-party plugins responsible for:
Those are core invariants.
Plugins ship their own React UI as a bundled module inside dist/ui/. The host loads plugin components into designated extension slots (pages, tabs, widgets, sidebar entries) and provides a bridge for the plugin frontend to talk to its own worker backend and to access host context.
How it works:
DashboardWidget, IssueDetailTab, SettingsPage).usePluginData(key, params) and usePluginAction(key).What the host controls: where plugin components appear, the bridge API, capability enforcement, and shared UI primitives (@paperclipai/plugin-sdk/ui) with design tokens and common components.
What the plugin controls: how to render its data, what data to fetch, what actions to expose, and whether to use the host's shared components or build entirely custom UI.
First version extension slots:
The host SDK ships shared components (MetricCard, DataTable, StatusBadge, LogView, etc.) for visual consistency, but these are optional.
Later, if untrusted third-party plugins become common, the host can move to iframe-based isolation without changing the plugin's source code (the bridge API stays the same).
opencode is mostly user-level local config.
Paperclip should treat plugin installation as a global instance-level action.
Examples:
@paperclip/plugin-linear oncePaperclip already has a concrete workspace model for projects:
workspaces and primaryWorkspaceproject_workspacesThat means local/runtime plugins should generally anchor themselves to projects first, not invent a parallel workspace model.
Practical guidance:
In other words:
project is the business objectproject_workspace is the local runtime anchoropencode makes tools a first-class extension point. This is one of the highest-value surfaces for Paperclip too.
A Linear plugin should be able to contribute a search-linear-issues tool that agents use during runs. A git plugin should contribute create-branch and get-diff. A file browser plugin should contribute read-file and list-directory.
The key constraints:
linear:search-issues) so they cannot shadow core toolsagent.tools.register capabilityThis is a natural fit — the plugin already has the SDK context, the external API credentials, and the domain logic. Wrapping that in a tool definition is minimal additional work for the plugin author.
Plugins should be able to emit custom events that other plugins can subscribe to. For example, the git plugin detects a push and emits plugin.@paperclip/plugin-git.push-detected. The GitHub Issues plugin subscribes to that event and updates PR links.
This avoids plugins needing to coordinate through shared state or external channels. The host routes plugin events through the same event bus with the same delivery semantics as core events.
Plugin events use a plugin.<pluginId>.* namespace so they cannot collide with core events.
Plugins that declare an instanceConfigSchema should get an auto-generated settings form for free. The host renders text inputs, dropdowns, toggles, arrays, and secret-ref pickers directly from the JSON Schema.
For plugins that need richer settings UX, they can declare a settingsPage extension slot and ship a custom React component. Both approaches coexist.
This matters because settings forms are boilerplate that every plugin needs. Auto-generating them from the schema that already exists removes a significant chunk of authoring friction.
The spec should be explicit about what happens when a plugin worker stops — during upgrades, uninstalls, or instance restarts.
The recommended policy:
shutdown() with a configurable deadline (default 10 seconds)cancelledFor upgrades specifically: the old worker drains, the new worker starts. If the new version adds capabilities, it enters upgrade_pending until the operator approves.
When a plugin is uninstalled, its data (plugin_state, plugin_entities, plugin_jobs, etc.) should be retained for a grace period (default 30 days), not immediately deleted. The operator can reinstall within the grace period and recover state, or force-purge via CLI.
This matters because accidental uninstalls should not cause irreversible data loss.
Plugin logs via ctx.logger should be stored and queryable from the plugin settings page. The host should also capture raw stdout/stderr from the worker process as fallback.
The plugin health dashboard should show: worker status, uptime, recent logs, job success/failure rates, webhook delivery rates, and resource usage. The host should emit internal events (plugin.health.degraded, plugin.worker.crashed) that other plugins or dashboards can consume.
This is critical for operators. Without observability, debugging plugin issues requires SSH access and manual log tailing.
A @paperclipai/plugin-test-harness package should provide a mock host with in-memory stores, synthetic event emission, and getData/performAction/executeTool simulation. Plugin authors should be able to write unit tests without a running Paperclip instance.
A create-paperclip-plugin CLI should scaffold a working plugin with manifest, worker, UI bundle, test file, and build config.
Low authoring friction was called out as one of opencode's best qualities. The test harness and starter template are how Paperclip achieves the same.
Plugin install, uninstall, upgrade, and config changes should take effect without restarting the Paperclip server. This is critical for developer workflow and operator experience.
The out-of-process worker architecture makes this natural:
plugin_config, notify the running worker via IPC (configChanged). The worker applies the change without restarting. If it doesn't handle configChanged, the host restarts just that worker.Frontend cache invalidation uses versioned or content-hashed bundle URLs and a plugin.ui.updated event that triggers re-import without a full page reload.
Each worker process is independent — starting, stopping, or replacing one worker never affects any other plugin or the host itself.
opencode does not have a formal SDK versioning story because plugins run in-process and are effectively pinned to the current runtime. Paperclip's out-of-process model means plugins may be built against one SDK version and run on a host that has moved forward. This needs explicit rules.
Recommended approach:
@paperclipai/plugin-sdk with subpath exports — root for worker code, /ui for frontend code. One dependency, one version, one changelog.@paperclipai/[email protected] targets apiVersion: 2. Plugins built with SDK 1.x declare apiVersion: 1 and continue to work.apiVersion simultaneously with separate IPC protocol handlers per version.sdkVersion in manifest: Plugins declare a semver range (e.g. ">=1.4.0 <2.0.0"). The host validates this at install time.An intentionally narrow first pass could look like this:
import { definePlugin, z } from "@paperclipai/plugin-sdk";
export default definePlugin({
id: "@paperclip/plugin-linear",
version: "0.1.0",
categories: ["connector", "ui"],
capabilities: [
"events.subscribe",
"jobs.schedule",
"http.outbound",
"instance.settings.register",
"ui.dashboardWidget.register",
"secrets.read-ref",
],
instanceConfigSchema: z.object({
linearBaseUrl: z.string().url().optional(),
companyMappings: z.array(
z.object({
companyId: z.string(),
teamId: z.string(),
apiTokenSecretRef: z.string(),
}),
).default([]),
}),
async register(ctx) {
ctx.jobs.register("linear-pull", { cron: "*/5 * * * *" }, async (job) => {
// sync Linear issues into plugin-owned state or explicit Paperclip entities
});
// subscribe with optional server-side filter
ctx.events.on("issue.created", { projectId: "proj-1" }, async (event) => {
// only receives issue.created events for project proj-1
});
// subscribe to events from another plugin
ctx.events.on("plugin.@paperclip/plugin-git.push-detected", async (event) => {
// react to the git plugin detecting a push
});
// contribute a tool that agents can use during runs
ctx.tools.register("search-linear-issues", {
displayName: "Search Linear Issues",
description: "Search for Linear issues by query",
parametersSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
}, async (params, runCtx) => {
// search Linear API and return results
return { content: JSON.stringify(results) };
});
// getData is called by the plugin's own UI components via the host bridge
ctx.data.register("sync-health", async ({ companyId }) => {
// return typed JSON that the plugin's DashboardWidget component renders
return { syncedCount: 142, trend: "+12 today", mappings: [...] };
});
ctx.actions.register("resync", async ({ companyId }) => {
// run sync logic
});
},
});
The plugin's UI bundle (separate from the worker) might look like:
// dist/ui/index.tsx
import { usePluginData, usePluginAction, MetricCard, ErrorBoundary } from "@paperclipai/plugin-sdk/ui";
export function DashboardWidget({ context }: PluginWidgetProps) {
const { data, loading, error } = usePluginData("sync-health", { companyId: context.companyId });
const resync = usePluginAction("resync");
if (loading) return <Spinner />;
if (error) return <div>Plugin error: {error.message} ({error.code})</div>;
return (
<ErrorBoundary fallback={<div>Widget failed to render</div>}>
<MetricCard label="Synced Issues" value={data.syncedCount} trend={data.trend} />
<button onClick={() => resync({ companyId: context.companyId })}>Resync Now</button>
</ErrorBoundary>
);
}
The important point is not the exact syntax. The important point is the contract shape:
These should stay close to the current registry style.
Candidates:
registerAgentAdapter()registerStorageProvider()registerSecretProvider()registerRunLogStore()These are trusted platform modules, not casual plugins.
These are the best near-term plugin candidates.
Capabilities:
/api/plugins/:pluginId/...Examples:
Workspace plugins handle local tooling directly:
Plugins resolve workspace paths through host APIs (ctx.projects provides workspace metadata including cwd, repoUrl, etc.) and then operate on the filesystem, spawn processes, shell out to git, or open PTY sessions using standard Node APIs or any libraries they choose.
The host does not wrap or proxy these operations. This keeps the core lean — no need to maintain a parallel API surface for every OS-level operation a plugin might need. Plugins own their own implementations.
Any Paperclip plugin system has to preserve core control-plane invariants from the repo docs.
That means:
I would require the following for every plugin:
Every plugin declares a static capability set such as:
companies.readissues.readissues.writeevents.subscribeevents.emitjobs.schedulehttp.outboundwebhooks.receiveassets.readassets.writesecrets.read-refagent.tools.registerplugin.state.readplugin.state.writeThe board/operator sees this before installation.
A plugin is installed once and becomes available across the instance. If it needs mappings over specific Paperclip objects, those are plugin data, not enable/disable boundaries.
Plugin-originated mutations should flow through the same activity log mechanism, with a dedicated plugin actor type:
actor_type = pluginactor_id = <plugin-id> (e.g. @paperclip/plugin-linear)Each plugin should expose:
One broken plugin must not break the rest of the company.
Plugins should receive secret refs, not raw secret values in config persistence. Resolution should go through the existing secret provider abstraction.
Plugins should have:
This matters especially for sync connectors and workspace plugins.
I would avoid "arbitrary third-party plugin-defined SQL migrations" in the first version. That is too much power too early.
The right mental model is:
If a concept is becoming part of Paperclip's actual product model, it should get a normal first-party table.
Examples:
project_workspaces is already a core table because project workspaces are now part of Paperclip itselfFor most plugins, the host should provide a few generic persistence tables and the plugin stores namespaced records there.
This keeps the system manageable:
A lot of plugin data naturally hangs off existing Paperclip objects:
project or project_workspaceissuecompany, project, or goalproject_workspace, agent, or runThat gives a good default keying model before introducing custom tables.
If Paperclip eventually needs extension-owned tables, I would only allow that for:
I would not let random third-party plugins run free-form schema migrations on startup.
Instead, add a controlled mechanism later if it becomes necessary.
pluginsInstance-level installation record.
Suggested fields:
idpackage_nameversioncategoriesmanifest_jsoninstalled_atstatusplugin_configInstance-level plugin config.
Suggested fields:
idplugin_idconfig_jsoncreated_atupdated_atlast_errorplugin_stateGeneric key/value state for plugins.
Suggested fields:
idplugin_idscope_kind (instance | company | project | project_workspace | agent | issue | goal | run)scope_id nullablenamespacestate_keyvalue_jsonupdated_atThis is enough for many connectors before allowing custom tables.
Examples:
issueprojectproject_workspaceproject_workspaceproject_workspace or runplugin_jobsScheduled job and run tracking.
Suggested fields:
idplugin_idscope_kind nullablescope_id nullablejob_keystatuslast_started_atlast_finished_atlast_errorplugin_webhook_deliveriesIf plugins expose webhooks, delivery history is worth storing.
Suggested fields:
idplugin_idscope_kind nullablescope_id nullableendpoint_keystatusreceived_atresponse_codeerrorplugin_entitiesIf generic plugin state becomes too limiting, add a structured, queryable entity table for connector records before allowing arbitrary plugin migrations.
Suggested fields:
idplugin_identity_typescope_kindscope_idexternal_idtitlestatusdata_jsonupdated_atThis is a useful middle ground:
| Use case | Best fit | Host primitives needed | Notes |
|---|---|---|---|
| File browser | workspace plugin | project workspace metadata | plugin owns filesystem ops directly |
| Terminal | workspace plugin | project workspace metadata | plugin spawns PTY sessions directly |
| Git workflow | workspace plugin | project workspace metadata | plugin shells out to git directly |
| Linear issue tracking | connector plugin | jobs, webhooks, secret refs, issue sync API | very strong plugin candidate |
| GitHub issue tracking | connector plugin | jobs, webhooks, secret refs | very strong plugin candidate |
| Grafana metrics | connector plugin + dashboard widget | outbound HTTP | probably read-only first |
| Child process/server tracking | workspace plugin | project workspace metadata | plugin manages processes directly |
| Stripe revenue tracking | connector plugin | secret refs, scheduled sync, company metrics API | strong plugin candidate |
Package idea: @paperclip/plugin-workspace-files
This plugin lets the board inspect project workspaces, agent workspaces, generated artifacts, and issue-related files without dropping to the shell. It is useful for:
/settings/plugins/workspace-files/:companyPrefix/plugins/workspace-files/:companyPrefix/projects/:projectId?tab=files/:companyPrefix/issues/:issueId?tab=files/:companyPrefix/agents/:agentId?tab=workspaceMain screens and interactions:
project.primaryWorkspaceworkspacescwd, repoUrl, and repoRefCore workflows:
Recommended capabilities and extension points:
instance.settings.registerui.sidebar.registerui.page.registerui.detailTab.register for project, issue, and agentprojects.readproject.workspaces.readassets.writeactivity.log.writeThe plugin resolves workspace paths through ctx.projects and handles all filesystem operations (read, write, stat, search, list directory) directly using Node APIs.
Optional event subscriptions:
events.subscribe(agent.run.started)events.subscribe(agent.run.finished)events.subscribe(issue.attachment.created)Package idea: @paperclip/plugin-terminal
This plugin gives the board a controlled terminal UI for project workspaces and agent workspaces. It is useful for:
/settings/plugins/terminal/:companyPrefix/plugins/terminal/:companyPrefix/projects/:projectId?tab=terminal/:companyPrefix/agents/:agentId?tab=terminal/:companyPrefix/agents/:agentId/runs/:runId?tab=terminalMain screens and interactions:
Core workflows:
Recommended capabilities and extension points:
instance.settings.registerui.sidebar.registerui.page.registerui.detailTab.register for project, agent, and runprojects.readproject.workspaces.readactivity.log.writeThe plugin resolves workspace paths through ctx.projects and handles PTY session management (open, input, resize, terminate, subscribe) directly using Node PTY libraries.
Optional event subscriptions:
events.subscribe(agent.run.started)events.subscribe(agent.run.failed)events.subscribe(agent.run.cancelled)Package idea: @paperclip/plugin-git
This plugin adds repo-aware workflow tooling around issues and workspaces. It is useful for:
/settings/plugins/git/:companyPrefix/plugins/git/:companyPrefix/projects/:projectId?tab=git/:companyPrefix/issues/:issueId?tab=git/:companyPrefix/agents/:agentId?tab=gitMain screens and interactions:
project.primaryWorkspace unless a different project workspace is chosencwd, repoUrl, repoRef)Core workflows:
Recommended capabilities and extension points:
instance.settings.registerui.sidebar.registerui.page.registerui.detailTab.register for project, issue, and agentui.action.registerprojects.readproject.workspaces.readagent.tools.register (e.g. create-branch, get-diff, get-status)events.emit (e.g. plugin.@paperclip/plugin-git.push-detected)activity.log.writeThe plugin resolves workspace paths through ctx.projects and handles all git operations (status, diff, log, branch create, commit, worktree create, push) directly using git CLI or a git library.
Optional event subscriptions:
events.subscribe(issue.created)events.subscribe(issue.updated)events.subscribe(agent.run.finished)The git plugin can emit plugin.@paperclip/plugin-git.push-detected events that other plugins (e.g. GitHub Issues) subscribe to for cross-plugin coordination.
Note: GitHub/GitLab PR creation should likely live in a separate connector plugin rather than overloading the local git plugin.
Package idea: @paperclip/plugin-linear
This plugin syncs Paperclip work with Linear. It is useful for:
/settings/plugins/linear/:companyPrefix/plugins/linear/:companyPrefix/dashboard/:companyPrefix/issues/:issueId?tab=linear/:companyPrefix/projects/:projectId?tab=linearMain screens and interactions:
Core workflows:
Recommended capabilities and extension points:
instance.settings.registerui.sidebar.registerui.page.registerui.dashboardWidget.registerui.detailTab.register for issue and projectevents.subscribe(issue.created)events.subscribe(issue.updated)events.subscribe(issue.comment.created)events.subscribe(project.updated)jobs.schedulewebhooks.receivehttp.outboundsecrets.read-refplugin.state.readplugin.state.writeissues.createissues.updateissue.comments.createagent.tools.register (e.g. search-linear-issues, get-linear-issue)activity.log.writeImportant constraint:
Package idea: @paperclip/plugin-github-issues
This plugin syncs Paperclip issues with GitHub Issues and optionally links PRs. It is useful for:
/settings/plugins/github-issues/:companyPrefix/plugins/github-issues/:companyPrefix/dashboard/:companyPrefix/issues/:issueId?tab=github/:companyPrefix/projects/:projectId?tab=githubMain screens and interactions:
Core workflows:
Recommended capabilities and extension points:
instance.settings.registerui.sidebar.registerui.page.registerui.dashboardWidget.registerui.detailTab.register for issue and projectevents.subscribe(issue.created)events.subscribe(issue.updated)events.subscribe(issue.comment.created)events.subscribe(plugin.@paperclip/plugin-git.push-detected) (cross-plugin coordination)jobs.schedulewebhooks.receivehttp.outboundsecrets.read-refplugin.state.readplugin.state.writeissues.createissues.updateissue.comments.createactivity.log.writeImportant constraint:
Package idea: @paperclip/plugin-grafana
This plugin surfaces external metrics and dashboards inside Paperclip. It is useful for:
/settings/plugins/grafana/:companyPrefix/plugins/grafana/:companyPrefix/dashboard/:companyPrefix/goals/:goalId?tab=metricsMain screens and interactions:
Core workflows:
Recommended capabilities and extension points:
instance.settings.registerui.dashboardWidget.registerui.page.registerui.detailTab.register for goal or projectjobs.schedulehttp.outboundsecrets.read-refplugin.state.readplugin.state.writeissues.createassets.writeactivity.log.writeOptional event subscriptions:
events.subscribe(goal.created)events.subscribe(project.updated)Important constraint:
Package idea: @paperclip/plugin-runtime-processes
This plugin tracks long-lived local processes and dev servers started in project workspaces. It is useful for:
/settings/plugins/runtime-processes/:companyPrefix/plugins/runtime-processes/:companyPrefix/dashboard/:companyPrefix/plugins/runtime-processes/:processId/:companyPrefix/projects/:projectId?tab=processes/:companyPrefix/agents/:agentId?tab=processesMain screens and interactions:
Core workflows:
Recommended capabilities and extension points:
instance.settings.registerui.sidebar.registerui.page.registerui.dashboardWidget.registerui.detailTab.register for project and agentprojects.readproject.workspaces.readplugin.state.readplugin.state.writeactivity.log.writeThe plugin resolves workspace paths through ctx.projects and handles process management (register, list, terminate, restart, read logs, health probes) directly using Node APIs.
Optional event subscriptions:
events.subscribe(agent.run.started)events.subscribe(agent.run.finished)Package idea: @paperclip/plugin-stripe
This plugin pulls Stripe revenue and subscription data into Paperclip. It is useful for:
/settings/plugins/stripe/:companyPrefix/plugins/stripe/:companyPrefix/dashboardMain screens and interactions:
Core workflows:
Recommended capabilities and extension points:
instance.settings.registerui.dashboardWidget.registerui.page.registerjobs.schedulewebhooks.receivehttp.outboundsecrets.read-refplugin.state.readplugin.state.writemetrics.writeissues.createactivity.log.writeImportant constraint:
This is the highest-value, lowest-risk plugin category.
Build:
@paperclipai/plugin-sdk/uiinstanceConfigSchemaPluginBridgeError)plugin.<pluginId>.* namespace)@paperclipai/plugin-test-harness and create-paperclip-plugin starter templateThis phase would immediately cover:
Workspace plugins do not require additional host APIs — they resolve workspace paths through ctx.projects and handle filesystem, git, PTY, and process operations directly.
Only after Phase 1 is stable:
If I had to collapse this report into one architectural decision, it would be:
Paperclip should not implement "an OpenCode-style generic in-process hook system." Paperclip should implement "a plugin platform with multiple trust tiers":
That gets the upside of opencode's extensibility without importing the wrong threat model.
platform modules and plugins.packages/shared and a plugins install/config section in the instance config.plugin.* namespace for cross-plugin events. Keep core invariants non-hookable.ctx.logger, health dashboard, internal health events.@paperclipai/plugin-test-harness and create-paperclip-plugin starter template.