## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The CLI (`paperclipai plugin ...`) installs and manages plugins
against a Paperclip server resolved from `--api-base` /
`PAPERCLIP_API_URL` / the active profile / an inferred default
> - During local plugin development you can have more than one Paperclip
running (a released host plus a branch build on another port), and
nothing told you *which* instance a command actually talked to
> - So a plugin that depends on a route or response field only present
on a feature branch could be silently installed/tested against a stale
host, returning `API route not found`, and look broken when the real
problem was the test target
> - This pull request makes the install target explicit: it probes `GET
/api/health` and prints the resolved API URL + server
status/version/mode/exposure before installing, and adds a `plugin
target` command plus docs for running and verifying against a branch
service
> - The benefit is that local plugin authors can confirm they are
exercising the runtime they intend to, instead of debugging phantom
plugin bugs caused by hitting the wrong server
## Linked Issues or Issue Description
No public GitHub issue exists, so the underlying problem is described
inline following the feature-request template.
**Problem or motivation**
Local plugin development assumes a single Paperclip on
`http://127.0.0.1:3100`. When a plugin depends on server code that only
exists on a feature branch (a new scoped route, a new response field, a
new managed-resource capability), installing it into a long-lived host
still on older code makes the route/field missing there. The plugin
falls back or errors and *looks* broken, when the real cause is that it
was tested against the wrong runtime. The CLI already let you point at
any server, but it never surfaced which server you ended up on — so the
mistake was invisible.
**Proposed solution**
Make the install target explicit. Before `plugin install` runs, probe
`GET /api/health` and print the resolved API URL plus server
status/version/deploymentMode/exposure, so the developer can confirm
which Paperclip they are installing into. Add a standalone `plugin
target` command to inspect the target without installing, a
`--no-verify-target` escape hatch, and docs covering how to run a branch
service on its own port and verify a branch route end-to-end.
**Alternatives considered**
- Do nothing and rely on the existing `--api-base` / `PAPERCLIP_API_URL`
resolution — rejected because the gap was never the inability to point
at a branch server, it was the lack of feedback about which server was
actually hit.
- Fail the install when the target looks stale — rejected as too
aggressive; the probe is advisory and degrades gracefully when health
details are not exposed or the server is unreachable.
## Dedup Search
- [x] I searched the open and recently closed GitHub PRs for similar or
duplicate PRs — this is not a duplicate
## What Changed
- Add `probeTargetDiagnostics` / `formatTargetDiagnostics` helpers
(`cli/src/commands/client/plugin.ts`) that read `GET /api/health` and
report the resolved API URL plus server `status` / `version` /
`deploymentMode` / `deploymentExposure`.
- `plugin install` now prints these target diagnostics before
installing, so you can confirm which instance you are installing into.
Skippable with `--no-verify-target`.
- `plugin install --json` keeps its original flat `PluginRecord` shape
(top-level `id` / `pluginKey` / `version` / `status` are unchanged);
when the target was probed it gains an additional top-level `target`
field. Existing automation that reads the plugin fields keeps working.
- Add a standalone `paperclipai plugin target` command to inspect the
install target without installing anything.
- Update `doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.md`: how the CLI resolves
its target, how to run a branch service on its own port and point the
CLI at it explicitly, an end-to-end check that the branch route is
actually served, and a troubleshooting entry for the stale-target
symptom.
- Unit tests for the diagnostics helpers (reachable + unreachable probe,
and both render paths).
## Verification
- `npx vitest run cli/src/__tests__/plugin-init.test.ts` — 10/10 pass
(covers `probeTargetDiagnostics` success/failure and
`formatTargetDiagnostics` rendering).
- CLI typecheck (`tsc --noEmit` in `cli/`) — clean.
- Manual: with a server running, `paperclipai plugin target` prints
`Target Paperclip: <url>` and the health line; `plugin install` prints
the same block before installing and `--no-verify-target` skips it.
## Risks
Low risk. The probe is read-only (`GET /api/health`) and runs before
install; if the server does not expose details it degrades to `ok (no
details exposed)`, and an unreachable target prints a remediation hint
rather than failing the command. The `--json` output keeps its original
flat shape, so existing scripts are unaffected. No server or schema
changes.
## Model Used
Claude Opus 4.7 (`claude-opus-4-7`), extended thinking + tool use, via
Claude Code.
## Thinking Path
> - Paperclip is the control plane for autonomous AI-agent companies.
> - Plugins are the extension point for adding capabilities without
expanding the core product surface.
> - Local plugin development needed a tighter CLI-first loop so plugin
authors can scaffold, run, install, inspect, and reload plugins without
reaching into internal package paths.
> - The server plugin install path also needed local-path handling that
keeps plugin identity, dashboard routes, and development watchers
coherent.
> - This pull request adds the CLI scaffold/install workflow, fixes the
server and SDK edge cases that blocked that loop, and updates the
agent-facing plugin creation skill and docs.
> - The benefit is that contributors can develop plugins from local
folders with a documented, repeatable happy path.
## What Changed
- Added `paperclipai plugin init` coverage and CLI wiring for local
plugin scaffolding.
- Improved local plugin install handling, plugin key route resolution,
dashboard capability behavior, and dev watcher startup/reload behavior.
- Fixed plugin SDK worker entrypoint validation for symlinked package
layouts.
- Added targeted tests for plugin init, server plugin authz/watcher
behavior, SDK worker host validation, and the authoring smoke example.
- Added a short local plugin development guide and refreshed the plugin
authoring guide plus `paperclip-create-plugin` skill instructions.
## Verification
- `pnpm run preflight:workspace-links && pnpm --filter
@paperclipai/plugin-sdk build && pnpm --filter
@paperclipai/create-paperclip-plugin typecheck && pnpm --filter
paperclipai typecheck && pnpm --filter @paperclipai/plugin-sdk typecheck
&& pnpm --filter @paperclipai/server typecheck`
- `pnpm exec vitest run --project paperclipai
cli/src/__tests__/plugin-init.test.ts`
- `pnpm exec vitest run --project @paperclipai/plugin-sdk
packages/plugins/sdk/tests/worker-rpc-host.test.ts`
- `pnpm exec vitest run --project @paperclipai/server
server/src/__tests__/plugin-dev-watcher.test.ts --pool=forks
--poolOptions.forks.isolate=true`
- `pnpm exec vitest run --project @paperclipai/server
server/src/__tests__/plugin-routes-authz.test.ts --pool=forks
--poolOptions.forks.isolate=true`
- `pnpm --dir packages/plugins/examples/plugin-authoring-smoke-example
test`
- Confirmed `pnpm-lock.yaml` is not included in the PR diff.
## Risks
- Medium risk: this touches plugin install routing, CLI command
behavior, and the local development watcher.
- Local path plugin installs execute trusted local code by design; the
new docs call out that trust boundary.
- No database migrations are included.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- OpenAI Codex, GPT-5 coding agent, tool-enabled local shell and git
workflow, medium reasoning effort. Context window details were not
exposed in this runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
UI screenshots: not applicable; this PR changes CLI/server/plugin docs
and tests, not board UI rendering.
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Devin Foley
Dotta