paperclip/doc/plugins/ideas-from-opencode.md

Plugin Ideas From OpenCode

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.

Executive Summary

opencode has a real plugin system already. It is intentionally low-friction:

• plugins are plain JS/TS modules
• they load from local directories and npm packages
• they can hook many runtime events
• they can add custom tools
• they can extend provider auth flows
• they run in-process and can mutate runtime behavior directly

That model works well for a local coding tool. It should not be copied literally into Paperclip.

The main conclusion is:

• Paperclip should copy opencode's typed SDK, deterministic loading, low authoring friction, and clear extension surfaces.
• Paperclip should not copy opencode's trust model, project-local plugin loading, "override by name collision" behavior, or arbitrary in-process mutation hooks for core business logic.
• Paperclip should use multiple extension classes instead of one generic plugin bag:
  • trusted in-process modules for low-level platform concerns like agent adapters, storage providers, secret providers, and possibly run-log backends
  • out-of-process plugins for most third-party integrations like Linear, GitHub Issues, Grafana, Stripe, and schedulers
  • schema-driven UI contributions for dashboard widgets, settings panels, and company pages
  • a typed event bus plus scheduled jobs for automation

If Paperclip does this well, the examples you listed become straightforward:

• file browser / terminal / git workflow / child process tracking become workspace-runtime plugins built on first-party primitives
• Linear / GitHub / Grafana / Stripe become connector plugins
• future knowledge base and accounting features can also fit the same model

Sources Examined

I cloned anomalyco/opencode and reviewed commit:

• a965a062595403a8e0083e85770315d5dc9628ab

Primary files reviewed:

• https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/plugin/src/index.ts
• https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/plugin/src/tool.ts
• https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/plugin/index.ts
• https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/config/config.ts
• https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/tool/registry.ts
• https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/provider/auth.ts
• https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/web/src/content/docs/plugins.mdx
• https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/web/src/content/docs/custom-tools.mdx
• https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/web/src/content/docs/ecosystem.mdx

Relevant Paperclip files reviewed for current extension seams:

• server/src/adapters/registry.ts
• ui/src/adapters/registry.ts
• server/src/storage/provider-registry.ts
• server/src/secrets/provider-registry.ts
• server/src/services/run-log-store.ts
• server/src/services/activity-log.ts
• doc/SPEC.md
• doc/SPEC-implementation.md

What OpenCode Actually Implements

1. Plugin authoring API

opencode exposes a small package, @opencode-ai/plugin, with a typed Plugin function and a typed tool() helper.

Core shape:

• a plugin is an async function that receives a context object
• the plugin returns a Hooks object
• hooks are optional
• plugins can also contribute tools and auth providers

The plugin init context includes:

• an SDK client
• current project info
• current directory
• current git worktree
• server URL
• Bun shell access

That is important: opencode gives plugins rich runtime power immediately, not a narrow capability API.

2. Hook model

The hook set is broad. It includes:

• event subscription
• config-time hook
• message hooks
• model parameter/header hooks
• permission decision hooks
• shell env injection
• tool execution before/after hooks
• tool definition mutation
• compaction prompt customization
• text completion transforms

The implementation pattern is very simple:

• core code constructs an output object
• each matching plugin hook runs sequentially
• hooks mutate the output
• final mutated output is used by core

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

3. Plugin discovery and load order

opencode supports two plugin sources:

• local files
• npm packages

Local directories:

• ~/.config/opencode/plugins/
• .opencode/plugins/

Npm plugins:

• listed in config under plugin: []

Load order is deterministic and documented:

1. global config
2. project config
3. global plugin directory
4. project plugin directory

Important details:

• config arrays are concatenated rather than replaced
• duplicate plugin names are deduplicated with higher-precedence entries winning
• internal first-party plugins and default plugins are also loaded through the plugin pipeline

This gives opencode a real precedence model rather than "whatever loaded last by accident."

4. Dependency handling

For local config/plugin directories, opencode will:

• ensure a package.json exists
• inject @opencode-ai/plugin
• run bun install

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

5. Error handling

Plugin load failures do not hard-crash the runtime by default.

Instead, opencode:

• logs the error
• publishes a session error event
• continues loading other plugins

That is a good operational pattern. One bad plugin should not brick the entire product unless the operator has explicitly configured it as required.

6. Tools are a first-class extension point

opencode has two ways to add tools:

• export tools directly from a plugin via hook.tool
• define local files in .opencode/tools/ or global tools directories

The tool API is strong:

• tools have descriptions
• tools have Zod schemas
• tool execution gets context like session ID, message ID, directory, and worktree
• tools are merged into the same registry as built-in tools
• tool definitions themselves can be mutated by a tool.definition hook

The most aggressive part of the design:

• custom tools can override built-in tools by name

That is very powerful for a local coding assistant. It is too dangerous for Paperclip core actions.

7. Auth is also a plugin surface

opencode allows plugins to register auth methods for providers.

A plugin can contribute:

• auth method metadata
• prompt flows
• OAuth flows
• API key flows
• request loaders that adapt provider behavior after auth succeeds

This is a strong pattern worth copying. Integrations often need custom auth UX and token handling.

8. Ecosystem evidence

The ecosystem page is the best proof that the model is working in practice. Community plugins already cover:

• sandbox/workspace systems
• auth providers
• session headers / telemetry
• memory/context features
• scheduling
• notifications
• worktree helpers
• background agents
• monitoring

That validates the main thesis: a simple typed plugin API can create real ecosystem velocity.

What OpenCode Gets Right

1. Separate plugin SDK from host runtime

This is one of the best parts of the design.

• plugin authors code against a clean public package
• host internals can evolve behind the loader
• runtime code and plugin code have a clean contract boundary

Paperclip should absolutely do this.

2. Deterministic loading and precedence

opencode is explicit about:

• where plugins come from
• how config merges
• what order wins

Paperclip should copy this discipline.

3. Low-ceremony authoring

A plugin author does not have to learn a giant framework.

• export async function
• return hooks
• optionally export tools

That simplicity matters.

4. Typed tool definitions

The tool() helper is excellent:

• typed
• schema-based
• easy to document
• easy for runtime validation

Paperclip should adopt this style for plugin actions, automations, and UI schemas.

5. Built-in features and plugins use similar shapes

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.

6. Incremental extension, not giant abstraction upfront

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.

What Paperclip Should Not Copy Directly

1. In-process arbitrary plugin code as the default

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:

• secrets matter
• approval gates matter
• budgets matter
• mutating actions require auditability

Default third-party plugins should not run with unrestricted in-process access to server memory, DB handles, and secrets.

2. Project-local plugin loading

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:

• instance-installed plugin package

Paperclip should not auto-load arbitrary code from a workspace repo like .paperclip/plugins or project directories.

3. Arbitrary mutation hooks on core business decisions

Hooks like:

• permission.ask
• tool.execute.before
• chat.headers
• shell.env

make sense in opencode.

For Paperclip, equivalent hooks into:

• approval decisions
• issue checkout semantics
• activity log behavior
• budget enforcement

would be a mistake.

Core invariants should stay in core code, not become hook-rewritable.

4. Override-by-name collision

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:

• core routes
• core mutating actions
• auth behaviors
• permission evaluators
• budget logic
• audit logic

Extension should be additive or explicitly delegated, never accidental shadowing.

5. Auto-install and execute from user config

opencode's "install dependencies at startup" flow is ergonomic. For Paperclip it would be risky because it combines:

• package installation
• code loading
• execution

inside the control-plane server startup path.

Paperclip should require an explicit operator install step.

Why Paperclip Needs A Different Shape

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 Already Has Useful Pre-Plugin Seams

Paperclip has several extension-like seams already:

• server adapter registry: server/src/adapters/registry.ts
• UI adapter registry: ui/src/adapters/registry.ts
• storage provider registry: server/src/storage/provider-registry.ts
• secret provider registry: server/src/secrets/provider-registry.ts
• pluggable run-log store seam: server/src/services/run-log-store.ts
• activity log and live event emission: server/src/services/activity-log.ts

This is good news. Paperclip does not need to invent extensibility from scratch. It needs to unify and harden existing seams.

Recommended Paperclip Plugin Model

1. Use multiple extension classes

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	mixed: core workspace services plus plugin descriptors	high	needs local OS/workspace primitives but should reuse core services
UI contribution	dashboard widgets, settings forms, company panels	schema-driven first, remote React later if needed	medium	safer than arbitrary frontend code
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.

2. Keep low-level modules separate from third-party plugins

Paperclip already has this pattern implicitly:

• adapters are one thing
• storage providers are another
• secret providers are another

Keep that separation.

I would formalize it like this:

• module means trusted code loaded by the host for low-level runtime services
• plugin means integration code that talks to Paperclip through a typed plugin protocol and capability model

This avoids trying to force Stripe, a PTY terminal, and a new agent adapter into the same abstraction.

3. Prefer event-driven extensions over core-logic mutation

For third-party plugins, the primary API should be:

• subscribe to typed domain events
• read instance state, including company-bound business records when relevant
• register webhooks
• run scheduled jobs
• write plugin-owned state
• add additive UI surfaces
• invoke explicit Paperclip actions through the API

Do not make third-party plugins responsible for:

• deciding whether an approval passes
• intercepting issue checkout semantics
• rewriting activity log behavior
• overriding budget hard-stops

Those are core invariants.

4. Start with schema-driven UI contributions

Arbitrary third-party React bundles inside the board UI are possible later, but they should not be the first version.

First version should let plugins contribute:

• settings sections defined by JSON schema
• dashboard widgets with server-provided data
• sidebar entries with fixed shell rendering
• detail-page tabs that render plugin data through core UI components

Why:

• simpler to secure
• easier to keep visually coherent
• easier to preserve context and auditability
• easier to test

Later, if needed, Paperclip can support richer frontend extensions through versioned remote modules.

5. Make installation global and keep mappings/config separate

opencode is mostly user-level local config. Paperclip should treat plugin installation as a global instance-level action.

Examples:

• install @paperclip/plugin-linear once
• make it available everywhere immediately
• optionally store mappings over Paperclip objects if one company maps to a different Linear team than another

6. Use project workspaces as the primary anchor for local tooling

Paperclip already has a concrete workspace model for projects:

• projects expose workspaces and primaryWorkspace
• the database already has project_workspaces
• project routes already support creating, updating, and deleting workspaces
• heartbeat resolution already prefers project workspaces before falling back to task-session or agent-home workspaces

That means local/runtime plugins should generally anchor themselves to projects first, not invent a parallel workspace model.

Practical guidance:

• file browser should browse project workspaces first
• terminal sessions should be launchable from a project workspace
• git should treat the project workspace as the repo root anchor
• dev server and child-process tracking should attach to project workspaces
• issue and agent views can still deep-link into the relevant project workspace context

In other words:

• project is the business object
• project_workspace is the local runtime anchor
• plugins should build on that instead of creating an unrelated workspace model first

A Concrete SDK Shape For Paperclip

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",
  kind: ["connector", "ui"],
  capabilities: [
    "events.subscribe",
    "jobs.schedule",
    "http.outbound",
    "instance.settings",
    "dashboard.widget",
    "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
    });

    ctx.events.on("issue.created", async (event) => {
      // optional outbound sync
    });

    ctx.ui.registerDashboardWidget({
      id: "linear-health",
      title: "Linear",
      loader: async ({ companyId }) => ({ status: "ok" }),
    });
  },
});

The important point is not the exact syntax. The important point is the contract shape:

• typed manifest
• explicit capabilities
• explicit global config with optional company mappings
• event subscriptions
• jobs
• additive UI contributions

Recommended Core Extension Surfaces

1. Platform module surfaces

These should stay close to the current registry style.

Candidates:

• registerAgentAdapter()
• registerStorageProvider()
• registerSecretProvider()
• registerRunLogStore()
• maybe registerWorkspaceRuntime() later

These are trusted platform modules, not casual plugins.

2. Connector plugin surfaces

These are the best near-term plugin candidates.

Capabilities:

• subscribe to domain events
• define scheduled sync jobs
• expose plugin-specific API routes under /api/plugins/:pluginId/...
• use company secret refs
• write plugin state
• publish dashboard data
• log activity through core APIs

Examples:

• Linear issue sync
• GitHub issue sync
• Grafana dashboard cards
• Stripe MRR / subscription rollups

3. Workspace-runtime surfaces

Your local-ops examples need first-party primitives plus plugin contributions.

Examples:

• file browser
• terminal
• git workflow
• child process tracking
• local dev server tracking

These should not be arbitrary third-party code directly poking the host filesystem and PTY layer through ad-hoc hooks. Instead, Paperclip should add first-party services such as:

• project workspace service built on project_workspaces
• PTY session service
• process registry
• git service
• dev-server registry

Then plugins can add:

• UI panels on top of those services
• automations
• annotations
• external sync logic

This keeps sensitive local-machine behavior centralized and auditable.

4. UI contribution surfaces

Recommended first version:

• dashboard widgets
• settings panels
• detail-page tabs
• sidebar sections
• action buttons that invoke plugin routes

Recommended later version:

• richer remote UI modules

Recommended never or only with extreme caution:

• arbitrary override of core pages
• arbitrary replacement of routing/auth/layout logic

Governance And Safety Requirements

Any Paperclip plugin system has to preserve core control-plane invariants from the repo docs.

That means:

• plugin install is global to the instance
• "companies" remain business objects in the API and data model, not tenant boundaries
• approval gates remain core-owned
• budget hard-stops remain core-owned
• mutating actions are activity-logged
• secrets remain ref-based and redacted in logs

I would require the following for every plugin:

1. Capability declaration

Every plugin declares a static capability set such as:

• companies.read
• issues.read
• issues.write
• events.subscribe
• jobs.schedule
• http.outbound
• webhooks.receive
• assets.read
• assets.write
• workspace.pty
• workspace.fs.read
• workspace.fs.write
• secrets.read-ref

The board/operator sees this before installation.

2. Global 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.

3. Activity logging

Plugin-originated mutations should flow through the same activity log mechanism, with actor identity like:

• actor_type = system
• actor_id = plugin:@paperclip/plugin-linear

or a dedicated plugin actor type if you want stronger semantics later.

4. Health and failure reporting

Each plugin should expose:

• enabled/disabled state
• last successful run
• last error
• recent webhook/job history

One broken plugin must not break the rest of the company.

5. Secret handling

Plugins should receive secret refs, not raw secret values in config persistence. Resolution should go through the existing secret provider abstraction.

6. Resource limits

Plugins should have:

• timeout limits
• concurrency limits
• retry policies
• optional per-plugin budgets

This matters especially for sync connectors and workspace plugins.

Data Model Additions To Consider

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:

• reuse core tables when the data is clearly part of Paperclip itself
• use generic extension tables for most plugin-owned state
• only allow plugin-specific tables later, and only for trusted platform modules or a tightly controlled migration workflow

Recommended Postgres Strategy For Extensions

1. Core tables stay core

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 itself
• if a future "project git state" becomes a core feature rather than plugin-owned metadata, that should also be a first-party table

2. Most plugins should start in generic extension tables

For most plugins, the host should provide a few generic persistence tables and the plugin stores namespaced records there.

This keeps the system manageable:

• simpler migrations
• simpler backup/restore
• simpler portability story
• easier operator review
• fewer chances for plugin schema drift to break the instance

3. Scope plugin data to Paperclip objects before adding custom schemas

A lot of plugin data naturally hangs off existing Paperclip objects:

• project workspace plugin state should often scope to project or project_workspace
• issue sync state should scope to issue
• metrics widgets may scope to company, project, or goal
• process tracking may scope to project_workspace, agent, or run

That gives a good default keying model before introducing custom tables.

4. Add trusted module migrations later, not arbitrary plugin migrations now

If Paperclip eventually needs extension-owned tables, I would only allow that for:

• trusted first-party packages
• trusted platform modules
• maybe explicitly installed admin-reviewed plugins with pinned versions

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.

Suggested baseline extension tables

1. plugins

Instance-level installation record.

Suggested fields:

• id
• package_name
• version
• kind
• manifest_json
• installed_at
• status

2. plugin_config

Instance-level plugin config.

Suggested fields:

• id
• plugin_id
• config_json
• installed_at
• updated_at
• last_error

3. plugin_state

Generic key/value state for plugins.

Suggested fields:

• id
• plugin_id
• scope_kind (instance | company | project | project_workspace | agent | issue | goal | run)
• scope_id nullable
• namespace
• state_key
• value_json
• updated_at

This is enough for many connectors before allowing custom tables.

Examples:

• Linear external IDs keyed by issue
• GitHub sync cursors keyed by project
• file browser preferences keyed by project_workspace
• git branch metadata keyed by project_workspace
• process metadata keyed by project_workspace or run

4. plugin_jobs

Scheduled job and run tracking.

Suggested fields:

• id
• plugin_id
• scope_kind nullable
• scope_id nullable
• job_key
• status
• last_started_at
• last_finished_at
• last_error

5. plugin_webhook_deliveries

If plugins expose webhooks, delivery history is worth storing.

Suggested fields:

• id
• plugin_id
• scope_kind nullable
• scope_id nullable
• endpoint_key
• status
• received_at
• response_code
• error

6. Maybe later: plugin_entities

If generic plugin state becomes too limiting, add a structured, queryable entity table for connector records before allowing arbitrary plugin migrations.

Suggested fields:

• id
• plugin_id
• entity_type
• scope_kind
• scope_id
• external_id
• title
• status
• data_json
• updated_at

This is a useful middle ground:

• much more queryable than opaque key/value state
• still avoids letting every plugin create its own relational schema immediately

How The Requested Examples Map To This Model

Use case	Best fit	Core primitives needed	Notes
File browser	workspace plugin + schema UI	project workspaces, file API, audit rules	best anchored on project detail pages
Terminal	workspace plugin + PTY service	project workspaces, PTY/session service, process limits, audit events	should launch against a project workspace by default
Git workflow	workspace plugin	project workspaces, git service, repo/worktree model	project workspace is the natural repo anchor
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, widget API	probably read-only first
Child process/server tracking	workspace plugin	project workspaces, process registry, server heartbeat model	should attach processes to project workspaces when possible
Stripe revenue tracking	connector plugin	secret refs, scheduled sync, company metrics API	strong plugin candidate and aligns with future spec direction

Plugin Examples

Workspace File Browser

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:

• browsing files inside project workspaces
• debugging what an agent changed
• reviewing generated outputs before approval
• attaching files from a workspace to issues
• understanding repo layout for a company
• inspecting agent home workspaces in local-trusted mode

UX

• Settings page: /settings/plugins/workspace-files
• Main page: /:companyPrefix/plugins/workspace-files
• Project tab: /:companyPrefix/projects/:projectId?tab=files
• Optional issue tab: /:companyPrefix/issues/:issueId?tab=files
• Optional agent tab: /:companyPrefix/agents/:agentId?tab=workspace

Main screens and interactions:

• Plugin settings:
  • choose whether the plugin defaults to project.primaryWorkspace
  • choose which project workspaces are visible
  • choose whether file writes are allowed or read-only
  • choose whether hidden files are visible
• Main explorer page:
  • project picker at the top
  • workspace picker scoped to the selected project's workspaces
  • tree view on the left
  • file preview pane on the right
  • search box for filename/path search
  • actions: copy path, download file, attach to issue, open diff
• Project tab:
  • opens directly into the project's primary workspace
  • lets the board switch among all project workspaces
  • shows workspace metadata like cwd, repoUrl, and repoRef
• Issue tab:
  • resolves the issue's project and opens that project's workspace context
  • shows files linked to the issue
  • lets the board pull files from the project workspace into issue attachments
  • shows the path and last modified info for each linked file
• Agent tab:
  • shows the agent's current resolved workspace
  • if the run is attached to a project, links back to the project workspace view
  • lets the board inspect files the agent is currently touching

Core workflows:

• Board opens a project and browses its primary workspace files.
• Board switches from one project workspace to another when a project has multiple checkouts or repo references.
• Board opens an issue, attaches a generated artifact from the file browser, and leaves a review comment.
• Board opens an agent detail page to inspect the exact files behind a failing run.

Hooks needed

Recommended capabilities and extension points:

• instance.settings.register
• ui.sidebar.register
• ui.page.register
• ui.detailTab.register for project, issue, and agent
• projects.read
• project.workspaces.read
• workspace.fs.read
• optional workspace.fs.write
• workspace.fs.stat
• workspace.fs.search
• optional assets.write
• activity.log.write

Optional event subscriptions:

• events.subscribe(agent.run.started)
• events.subscribe(agent.run.finished)
• events.subscribe(issue.attachment.created)

Important constraint:

• the plugin should never read arbitrary host paths directly
• it should treat project workspaces as the canonical local file roots when a project is present
• it should only use first-party workspace/file APIs that enforce approved workspace roots

Workspace Terminal

Package idea: @paperclip/plugin-terminal

This plugin gives the board a controlled terminal UI for project workspaces and agent workspaces. It is useful for:

• debugging stuck runs
• verifying environment state
• running targeted manual commands
• watching long-running commands
• pairing a human operator with an agent workflow

UX

• Settings page: /settings/plugins/terminal
• Main page: /:companyPrefix/plugins/terminal
• Project tab: /:companyPrefix/projects/:projectId?tab=terminal
• Optional agent tab: /:companyPrefix/agents/:agentId?tab=terminal
• Optional run tab: /:companyPrefix/agents/:agentId/runs/:runId?tab=terminal

Main screens and interactions:

• Plugin settings:
  • allowed shells and shell policy
  • whether commands are read-only, free-form, or allow-listed
  • whether terminals require an explicit operator confirmation before launch
  • whether new terminal sessions default to the project's primary workspace
• Terminal home page:
  • list of active terminal sessions
  • button to open a new session
  • project picker, then workspace picker from that project's workspaces
  • optional agent association
  • terminal panel with input, resize, and reconnect support
  • controls: interrupt, kill, clear, save transcript
• Project terminal tab:
  • opens a session already scoped to the project's primary workspace
  • lets the board switch among the project's configured workspaces
  • shows recent commands and related process/server state for that project
• Agent terminal tab:
  • opens a session already scoped to the agent's workspace
  • shows recent related runs and commands
• Run terminal tab:
  • lets the board inspect the environment around a specific failed run

Core workflows:

• Board opens a terminal against an agent workspace to reproduce a failing command.
• Board opens a project page and launches a terminal directly in that project's primary workspace.
• Board watches a long-running dev server or test command from the terminal page.
• Board kills or interrupts a runaway process from the same UI.

Hooks needed

Recommended capabilities and extension points:

• instance.settings.register
• ui.sidebar.register
• ui.page.register
• ui.detailTab.register for project, agent, and run
• projects.read
• project.workspaces.read
• workspace.pty.open
• workspace.pty.input
• workspace.pty.resize
• workspace.pty.terminate
• workspace.pty.subscribe
• workspace.process.read
• activity.log.write

Optional event subscriptions:

• events.subscribe(agent.run.started)
• events.subscribe(agent.run.failed)
• events.subscribe(agent.run.cancelled)

Important constraint:

• shell spawning must stay in a first-party PTY service
• the plugin should orchestrate and render sessions, not spawn raw host processes by itself

Git Workflow

Package idea: @paperclip/plugin-git

This plugin adds repo-aware workflow tooling around issues and workspaces. It is useful for:

• branch creation tied to issues
• quick diff review
• commit and worktree visibility
• PR preparation
• treating the project's primary workspace as the canonical repo anchor
• seeing whether an agent's workspace is clean or dirty

UX

• Settings page: /settings/plugins/git
• Main page: /:companyPrefix/plugins/git
• Project tab: /:companyPrefix/projects/:projectId?tab=git
• Optional issue tab: /:companyPrefix/issues/:issueId?tab=git
• Optional agent tab: /:companyPrefix/agents/:agentId?tab=git

Main screens and interactions:

• Plugin settings:
  • branch naming template
  • optional remote provider token secret ref
  • whether write actions are enabled or read-only
  • whether the plugin always uses project.primaryWorkspace unless a different project workspace is chosen
• Git overview page:
  • project picker and workspace picker
  • current branch
  • ahead/behind status
  • dirty files summary
  • recent commits
  • active worktrees
  • actions: refresh, create branch, create worktree, stage all, commit, open diff
• Project tab:
  • opens in the project's primary workspace
  • shows workspace metadata and repo binding (cwd, repoUrl, repoRef)
  • shows branch, diff, and commit history for that project workspace
• Issue tab:
  • resolves the issue's project and uses that project's workspace context
  • "create branch from issue" action
  • diff view scoped to the project's selected workspace
  • link branch/worktree metadata to the issue
• Agent tab:
  • shows the agent's branch, worktree, and dirty state
  • shows recent commits produced by that agent
  • if the agent is working inside a project workspace, links back to the project git tab

Core workflows:

• Board creates a branch from an issue and ties it to the project's primary workspace.
• Board opens a project page and reviews the diff for that project's workspace without leaving Paperclip.
• Board reviews the diff after a run without leaving Paperclip.
• Board opens a worktree list to understand parallel branches across agents.

Hooks needed

Recommended capabilities and extension points:

• instance.settings.register
• ui.sidebar.register
• ui.page.register
• ui.detailTab.register for project, issue, and agent
• ui.action.register
• projects.read
• project.workspaces.read
• workspace.git.status
• workspace.git.diff
• workspace.git.log
• workspace.git.branch.create
• optional workspace.git.commit
• optional workspace.git.worktree.create
• optional workspace.git.push
• activity.log.write

Optional event subscriptions:

• events.subscribe(issue.created)
• events.subscribe(issue.updated)
• events.subscribe(agent.run.finished)

Important constraint:

• GitHub/GitLab PR creation should likely live in a separate connector plugin rather than overloading the local git plugin

Linear Issue Tracking

Package idea: @paperclip/plugin-linear

This plugin syncs Paperclip work with Linear. It is useful for:

• importing backlog from Linear
• linking Paperclip issues to Linear issues
• syncing status, comments, and assignees
• mapping company goals/projects to external product planning
• giving board operators a single place to see sync health

UX

• Settings page: /settings/plugins/linear
• Main page: /:companyPrefix/plugins/linear
• Dashboard widget: /:companyPrefix/dashboard
• Optional issue tab: /:companyPrefix/issues/:issueId?tab=linear
• Optional project tab: /:companyPrefix/projects/:projectId?tab=linear

Main screens and interactions:

• Plugin settings:
  • Linear API token secret ref
  • workspace/team/project mappings
  • status mapping between Paperclip and Linear
  • sync direction: import only, export only, bidirectional
  • comment sync toggle
• Linear overview page:
  • sync health card
  • recent sync jobs
  • mapped projects and teams
  • unresolved conflicts queue
  • import actions for teams, projects, and issues
• Issue tab:
  • linked Linear issue key and URL
  • sync status and last synced time
  • actions: link existing, create in Linear, resync now, unlink
  • timeline of synced comments/status changes
• Dashboard widget:
  • open sync errors
  • imported vs linked issues count
  • recent webhook/job failures

Core workflows:

• Board enables the plugin, maps a Linear team, and imports a backlog into Paperclip.
• Paperclip issue status changes push to Linear and Linear comments arrive back through webhooks.
• Board resolves mapping conflicts from the plugin page instead of silently drifting state.

Hooks needed

Recommended capabilities and extension points:

• instance.settings.register
• ui.sidebar.register
• ui.page.register
• ui.dashboardWidget.register
• ui.detailTab.register for issue and project
• events.subscribe(issue.created)
• events.subscribe(issue.updated)
• events.subscribe(issue.comment.created)
• events.subscribe(project.updated)
• jobs.schedule
• webhooks.receive
• http.outbound
• secrets.read-ref
• plugin.state.read
• plugin.state.write
• optional issues.create
• optional issues.update
• optional issue.comments.create
• activity.log.write

Important constraint:

• webhook processing should be idempotent and conflict-aware
• external IDs and sync cursors belong in plugin-owned state, not inline on core issue rows in the first version

GitHub Issue Tracking

Package idea: @paperclip/plugin-github-issues

This plugin syncs Paperclip issues with GitHub Issues and optionally links PRs. It is useful for:

• importing repo backlogs
• mirroring issue status and comments
• linking PRs to Paperclip issues
• tracking cross-repo work from inside one company view
• bridging engineering workflow with Paperclip task governance

UX

• Settings page: /settings/plugins/github-issues
• Main page: /:companyPrefix/plugins/github-issues
• Dashboard widget: /:companyPrefix/dashboard
• Optional issue tab: /:companyPrefix/issues/:issueId?tab=github
• Optional project tab: /:companyPrefix/projects/:projectId?tab=github

Main screens and interactions:

• Plugin settings:
  • GitHub App or PAT secret ref
  • org/repo mappings
  • label/status mapping
  • whether PR linking is enabled
  • whether new Paperclip issues should create GitHub issues automatically
• GitHub overview page:
  • repo mapping list
  • sync health and recent webhook events
  • import backlog action
  • queue of unlinked GitHub issues
• Issue tab:
  • linked GitHub issue and optional linked PRs
  • actions: create GitHub issue, link existing issue, unlink, resync
  • comment/status sync timeline
• Dashboard widget:
  • open PRs linked to active Paperclip issues
  • webhook failures
  • sync lag metrics

Core workflows:

• Board imports GitHub Issues for a repo into Paperclip.
• GitHub webhooks update status/comment state in Paperclip.
• A PR is linked back to the Paperclip issue so the board can follow delivery status.

Hooks needed

Recommended capabilities and extension points:

• instance.settings.register
• ui.sidebar.register
• ui.page.register
• ui.dashboardWidget.register
• ui.detailTab.register for issue and project
• events.subscribe(issue.created)
• events.subscribe(issue.updated)
• events.subscribe(issue.comment.created)
• jobs.schedule
• webhooks.receive
• http.outbound
• secrets.read-ref
• plugin.state.read
• plugin.state.write
• optional issues.create
• optional issues.update
• optional issue.comments.create
• activity.log.write

Important constraint:

• keep "local git state" and "remote GitHub issue state" in separate plugins even if they work together

Grafana Metrics

Package idea: @paperclip/plugin-grafana

This plugin surfaces external metrics and dashboards inside Paperclip. It is useful for:

• company KPI visibility
• infrastructure/incident monitoring
• showing deploy, traffic, latency, or revenue charts next to work
• creating Paperclip issues from anomalous metrics

UX

• Settings page: /settings/plugins/grafana
• Main page: /:companyPrefix/plugins/grafana
• Dashboard widgets: /:companyPrefix/dashboard
• Optional goal tab: /:companyPrefix/goals/:goalId?tab=metrics

Main screens and interactions:

• Plugin settings:
  • Grafana base URL
  • service account token secret ref
  • dashboard and panel mappings
  • refresh interval
  • optional alert threshold rules
• Dashboard widgets:
  • one or more metric cards on the main dashboard
  • quick trend view and last refresh time
  • link out to Grafana and link in to the full Paperclip plugin page
• Full metrics page:
  • selected dashboard panels embedded or proxied
  • metric selector
  • time range selector
  • "create issue from anomaly" action
• Goal tab:
  • metric cards relevant to a specific goal or project

Core workflows:

• Board sees service degradation or business KPI movement directly on the Paperclip dashboard.
• Board clicks into the full metrics page to inspect the relevant Grafana panels.
• Board creates a Paperclip issue from a threshold breach with a metric snapshot attached.

Hooks needed

Recommended capabilities and extension points:

• instance.settings.register
• ui.dashboardWidget.register
• ui.page.register
• ui.detailTab.register for goal or project
• jobs.schedule
• http.outbound
• secrets.read-ref
• plugin.state.read
• plugin.state.write
• optional issues.create
• optional assets.write
• activity.log.write

Optional event subscriptions:

• events.subscribe(goal.created)
• events.subscribe(project.updated)

Important constraint:

• start read-only first
• do not make Grafana alerting logic part of Paperclip core; keep it as additive signal and issue creation

Child Process / Server Tracking

Package idea: @paperclip/plugin-runtime-processes

This plugin tracks long-lived local processes and dev servers started in project workspaces. It is useful for:

• seeing which agent started which local service
• tracking ports, health, and uptime
• restarting failed dev servers
• exposing process state alongside issue and run state
• making local development workflows visible to the board

UX

• Settings page: /settings/plugins/runtime-processes
• Main page: /:companyPrefix/plugins/runtime-processes
• Dashboard widget: /:companyPrefix/dashboard
• Process detail page: /:companyPrefix/plugins/runtime-processes/:processId
• Project tab: /:companyPrefix/projects/:projectId?tab=processes
• Optional agent tab: /:companyPrefix/agents/:agentId?tab=processes

Main screens and interactions:

• Plugin settings:
  • whether manual process registration is allowed
  • health check behavior
  • whether operators can stop/restart processes
  • log retention preferences
• Process list page:
  • status table with name, command, cwd, owner agent, port, uptime, and health
  • filters for running/exited/crashed processes
  • actions: inspect, stop, restart, tail logs
• Project tab:
  • filters the process list to the project's workspaces
  • shows which workspace each process belongs to
  • groups processes by project workspace
• Process detail page:
  • process metadata
  • live log tail
  • health check history
  • links to associated issue or run
• Agent tab:
  • shows processes started by or assigned to that agent

Core workflows:

• An agent starts a dev server; the first-party process service registers it and the plugin renders it.
• Board opens a project and immediately sees the processes attached to that project's workspace.
• Board sees a crashed process on the dashboard and restarts it from the plugin page.
• Board attaches process logs to an issue when debugging a failure.

Hooks needed

Recommended capabilities and extension points:

• instance.settings.register
• ui.sidebar.register
• ui.page.register
• ui.dashboardWidget.register
• ui.detailTab.register for project and agent
• projects.read
• project.workspaces.read
• workspace.process.register
• workspace.process.list
• workspace.process.read
• optional workspace.process.terminate
• optional workspace.process.restart
• workspace.process.logs.read
• optional workspace.http.probe
• plugin.state.read
• plugin.state.write
• activity.log.write

Optional event subscriptions:

• events.subscribe(agent.run.started)
• events.subscribe(agent.run.finished)
• events.subscribe(process.started)
• events.subscribe(process.exited)

Important constraint:

• this should be built on a first-party process registry
• the plugin should not own raw child-process spawning on its own

Stripe Revenue Tracking

Package idea: @paperclip/plugin-stripe

This plugin pulls Stripe revenue and subscription data into Paperclip. It is useful for:

• showing MRR and churn next to company goals
• tracking trials, conversions, and failed payments
• letting the board connect revenue movement to ongoing work
• enabling future financial dashboards beyond token costs

UX

• Settings page: /settings/plugins/stripe
• Main page: /:companyPrefix/plugins/stripe
• Dashboard widgets: /:companyPrefix/dashboard
• Optional company/goal metric tabs if those surfaces exist later

Main screens and interactions:

• Plugin settings:
  • Stripe secret key secret ref
  • account selection if needed
  • metric definitions such as MRR treatment and trial handling
  • sync interval
  • webhook signing secret ref
• Dashboard widgets:
  • MRR card
  • active subscriptions
  • trial-to-paid conversion
  • failed payment alerts
• Stripe overview page:
  • time series charts
  • recent customer/subscription events
  • webhook health
  • sync history
  • action: create issue from billing anomaly

Core workflows:

• Board enables the plugin and connects a Stripe account.
• Webhooks and scheduled reconciliation keep plugin state current.
• Revenue widgets appear on the main dashboard and can be linked to company goals.
• Failed payment spikes or churn events can generate Paperclip issues for follow-up.

Hooks needed

Recommended capabilities and extension points:

• instance.settings.register
• ui.dashboardWidget.register
• ui.page.register
• jobs.schedule
• webhooks.receive
• http.outbound
• secrets.read-ref
• plugin.state.read
• plugin.state.write
• company.metrics.write
• optional issues.create
• activity.log.write

Important constraint:

• Stripe data should stay additive to Paperclip core
• it should not leak into core budgeting logic, which is specifically about model/token spend in V1

Specific Patterns From OpenCode Worth Adopting

Adopt

• separate SDK package from runtime loader
• deterministic load order and precedence
• very small authoring API
• typed schemas for plugin inputs/config/tools
• internal extensions using the same registration shapes as external ones when reasonable
• plugin load errors isolated from host startup when possible
• explicit community-facing plugin docs and example templates

Adapt, not copy

• local path loading
• dependency auto-install
• hook mutation model
• built-in override behavior
• broad runtime context objects

Avoid

• project-local arbitrary code loading
• implicit trust of npm packages at startup
• plugins overriding core invariants
• unsandboxed in-process execution as the default extension model

Suggested Rollout Plan

Phase 0: Harden the seams that already exist

• formalize adapter/storage/secret/run-log registries as "platform modules"
• remove ad-hoc fallback behavior where possible
• document stable registration contracts

Phase 1: Add connector plugins first

This is the highest-value, lowest-risk plugin category.

Build:

• plugin manifest
• global install/update lifecycle
• global plugin config and optional company-mapping storage
• secret ref access
• typed domain event subscription
• scheduled jobs
• webhook endpoints
• activity logging helpers
• dashboard widget and settings-panel contributions

This phase would immediately cover:

• Linear
• GitHub
• Grafana
• Stripe

Phase 2: Add workspace services and workspace plugins

Build first-party primitives:

• project workspace service built on project_workspaces
• PTY/session service
• file service
• git service
• process/service tracker

Then expose additive plugin/UI surfaces on top.

This phase covers:

• file browser
• terminal
• git workflow
• child process/server tracking

Phase 3: Consider richer UI and plugin packaging

Only after phases 1 and 2 are stable:

• richer frontend extension support
• signed/verified plugin packages
• plugin marketplace
• optional custom plugin storage backends or migrations

Recommended Architecture Decision

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":

• trusted platform modules for low-level runtime integration
• typed out-of-process plugins for instance-wide integrations and automation
• schema-driven UI contributions
• core-owned invariants that plugins can observe and act around, but not replace

That gets the upside of opencode's extensibility without importing the wrong threat model.

Concrete Next Steps I Would Take In Paperclip

1. Write a short extension architecture RFC that formalizes the distinction between platform modules and plugins.
2. Introduce a small plugin manifest type in packages/shared and a plugins install/config section in the instance config.
3. Build a typed domain event bus around existing activity/live-event patterns, but keep core invariants non-hookable.
4. Implement connector-plugin MVP only: global install/config, secret refs, jobs, webhooks, settings panel, dashboard widget.
5. Treat workspace features as a separate track that starts by building core workspace primitives, not raw plugin hooks.