Skip to content
Back to search

primer

MarketplaceWorks with Claude CodeGitHub

Primer HTML sharing and commenting tool for LLM output

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/0xPolygon/primer with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/0xPolygon/primer'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/0xpolygon--primer/badge.svg)](/listings/0xpolygon--primer)

HTML

<a href="/listings/0xpolygon--primer"><img src="/api/listings/0xpolygon--primer/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need:

- **Node.js 24** (the version in [`.nvmrc`](.nvmrc)). - **pnpm.** Run `corepack enable` once (Corepack comes with Node), or install a recent pnpm (10 or later) any way you like. Either way, the pnpm version pinned in `package.json` is the one that runs. - **Docker**, for the local Postgres.

git clone https://github.com/0xPolygon/primer.git && cd primer
cp .env.example .env              # the defaults work for local development
pnpm install --frozen-lockfile
pnpm db:up                        # Postgres 17 in Docker on localhost:5432
pnpm db:migrate                   # create the schema and seed two mock users
pnpm dev                          # API on :3000, web app on :5173

Open <http://localhost:5173>. Local development uses `AUTH_MODE=mock`, so you're already signed in as **Mock User** (`mock@polygon.technology`). To act as the second persona, **Mock Reviewer**, open <http://localhost:5173/auth/mock> in another browser or a private window and pick `mock-user-2`. That lets you try sharing and commenting between two users.

To publish your first document, use **Upload** in the app, or call the API:

echo '<h1>Hello, Primer</h1><p>Select this text to comment on it.</p>' > hello.html
curl -X POST http://localhost:3000/api/upload \
  -H 'x-primer-csrf: 1' -F file=@hello.html -F title='Hello'
# → {"documentId":"…","versionId":"…","url":"/d/…"}

Open `http://localhost:5173` followed by the returned `url`.

In development the API (port 3000) and the web app (port 5173, served by Vite) are two processes, and Vite forwards `/api`, `/auth` and `/companion` to the API. Point API clients and MCP clients at port 3000. In production, one process serves both.

To reach the API from other tools such as curl or an MCP client, create a token at <http://localhost:5173/settings/tokens> and send it as `Authorization: Bearer <token>`. Requests with a token don't need the `x-primer-csrf` header.

Useful scripts

| Command | What it does | |---|---| | `pnpm dev` | Start the API and the web app, with reload on change | | `pnpm db:up` / `pnpm db:down` | Start or stop the local Postgres | | `pnpm db:reset` | Delete the local database and migrate it again from scratch | | `pnpm db:migrate` | Apply migrations to the development database | | `pnpm db:migrate:test` | Apply migrations to the test database (`primer_test`) | | `pnpm db:generate` | Create a migration from changes to `apps/api/src/db/schema.ts` (commit the SQL) | | `pnpm typecheck` | Run `tsc --noEmit` in every package | | `pnpm test` | Run the Vitest suites (see [Testing](#testing)) | | `pnpm build` | Build every package | | `pnpm verify` | Typecheck, test, and `pnpm audit --audit-level=high` |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 22 lines
  1. {
  2. "name": "primer",
  3. "owner": {
  4. "name": "Polygon"
  5. },
  6. "metadata": {
  7. "description": "Publish and iterate on HTML/Markdown artifacts at a stable URL via Claude Web, Desktop, or Code. Browser-based OAuth login.",
  8. "version": "2.2.0",
  9. "pluginRoot": "./plugins"
  10. },
  11. "plugins": [
  12. {
  13. "name": "primer",
  14. "displayName": "Primer",
  15. "source": "./plugins/primer",
  16. "description": "Publish HTML/Markdown artifacts to Primer from Claude Web, Desktop, or Code. Browser-based OAuth login, create/version documents, pull reviewer comments.",
  17. "author": {
  18. "name": "Polygon"
  19. }
  20. }
  21. ]
  22. }
README.md · README · 272 lines
  1. # Primer
  2. > *"The Primer was a book in appearance only. Its interior was a tissue of paper, but each page was a separate flat-panel display, which formed itself into pictures, words, and animations responsive to the reader."*
  3. > — Neal Stephenson, *The Diamond Age*
  4. Primer is a place to publish HTML and Markdown documents, most often written by an
  5. LLM, at a stable URL, and to review them together. Upload a page (or have your
  6. agent publish it), share the link, and reviewers comment directly on the text.
  7. New versions keep the same URL, and the agent can pull the comments back in to
  8. write the next one.
  9. Polygon builds Primer and runs it for its own teams. The code is open source
  10. under MIT or Apache-2.0, and you can run your own instance.
  11. ## Contents
  12. - [What it does](#what-it-does)
  13. - [Publish from Claude and other agents](#publish-from-claude-and-other-agents)
  14. - [Quickstart: run it locally](#quickstart-run-it-locally)
  15. - [How the code is organized](#how-the-code-is-organized)
  16. - [Configuration](#configuration)
  17. - [Running your own instance](#running-your-own-instance)
  18. - [Testing](#testing)
  19. - [Contributing](#contributing)
  20. - [Security](#security)
  21. - [License](#license)
  22. ## What it does
  23. - **Publishing.** Upload a self-contained `.html` file or a `.md` file in the
  24. browser, or through the REST API and MCP tools. Markdown is rendered to HTML,
  25. with Mermaid diagrams supported.
  26. - **Sandboxed rendering.** Documents run in a sandboxed iframe. A small
  27. companion script inside the frame reports text selections and positions back
  28. to the app, so the document itself never touches your session.
  29. - **Anchored comments.** Select text to start a thread on it. Threads support
  30. replies, mentions and email notifications.
  31. - **Versions.** Each upload of a document is a new version at the same URL. You
  32. can switch between versions and see a diff between any two.
  33. - **Sharing.** Documents are private to the owner and the collaborators they
  34. add (editor, responder or commenter), or visible to everyone in the
  35. organization. A published version can also be shared with people outside the
  36. organization, who sign in with a code sent to their email.
  37. - **Agent access.** A remote MCP endpoint (`/mcp`, OAuth 2.1), a stdio MCP
  38. server published to npm, and a REST API with scoped personal and service
  39. tokens.
  40. - **Document events.** Interactive documents can submit structured events
  41. (for example, a form answer), which the owner's tooling reads back over the
  42. API or a live stream. See [the events loop guide](docs/development/events-loop.md).
  43. ## Publish from Claude and other agents
  44. This repository is also a Claude plugin marketplace. The `primer` plugin adds
  45. a skill that knows how to publish, version and read comments, and it connects
  46. to Polygon's hosted Primer. At Polygon, install it once in Claude Code:
  47. ```
  48. /plugin marketplace add 0xPolygon/primer
  49. /plugin install primer@primer
  50. /reload-plugins
  51. ```
  52. Then ask Claude to "publish this to Primer". The first time, it asks you to sign
  53. in through your browser.
  54. To use your own instance instead, point any MCP client at its remote endpoint,
  55. `https://<your-host>/mcp`, or run the stdio server
  56. [`@polygonlabs/primer-mcp`](apps/mcp/) with `PRIMER_API_URL` set to your host.
  57. [`apps/mcp/README.md`](apps/mcp/README.md) lists the tools and the login flow.
  58. ## Quickstart: run it locally
  59. You need:
  60. - **Node.js 24** (the version in [`.nvmrc`](.nvmrc)).
  61. - **pnpm.** Run `corepack enable` once (Corepack comes with Node), or install a
  62. recent pnpm (10 or later) any way you like. Either way, the pnpm version
  63. pinned in `package.json` is the one that runs.
  64. - **Docker**, for the local Postgres.
  65. ```bash
  66. git clone https://github.com/0xPolygon/primer.git && cd primer
  67. cp .env.example .env # the defaults work for local development
  68. pnpm install --frozen-lockfile
  69. pnpm db:up # Postgres 17 in Docker on localhost:5432
  70. pnpm db:migrate # create the schema and seed two mock users
  71. pnpm dev # API on :3000, web app on :5173
  72. ```
  73. Open <http://localhost:5173>. Local development uses `AUTH_MODE=mock`, so
  74. you're already signed in as **Mock User** (`mock@polygon.technology`). To act as
  75. the second persona, **Mock Reviewer**, open <http://localhost:5173/auth/mock>
  76. in another browser or a private window and pick `mock-user-2`. That lets you
  77. try sharing and commenting between two users.
  78. To publish your first document, use **Upload** in the app, or call the API:
  79. ```bash
  80. echo '<h1>Hello, Primer</h1><p>Select this text to comment on it.</p>' > hello.html
  81. curl -X POST http://localhost:3000/api/upload \
  82. -H 'x-primer-csrf: 1' -F file=@hello.html -F title='Hello'
  83. # → {"documentId":"…","versionId":"…","url":"/d/…"}
  84. ```
  85. Open `http://localhost:5173` followed by the returned `url`.
  86. In development the API (port 3000) and the web app (port 5173, served by
  87. Vite) are two processes, and Vite forwards `/api`, `/auth` and `/companion`
  88. to the API. Point API clients and MCP clients at port 3000. In production, one
  89. process serves both.
  90. To reach the API from other tools such as curl or an MCP client, create a
  91. token at <http://localhost:5173/settings/tokens> and send it as
  92. `Authorization: Bearer <token>`. Requests with a token don't need the
  93. `x-primer-csrf` header.
  94. ### Useful scripts
  95. | Command | What it does |
  96. |---|---|
  97. | `pnpm dev` | Start the API and the web app, with reload on change |
  98. | `pnpm db:up` / `pnpm db:down` | Start or stop the local Postgres |
  99. | `pnpm db:reset` | Delete the local database and migrate it again from scratch |
  100. | `pnpm db:migrate` | Apply migrations to the development database |
  101. | `pnpm db:migrate:test` | Apply migrations to the test database (`primer_test`) |
  102. | `pnpm db:generate` | Create a migration from changes to `apps/api/src/db/schema.ts` (commit the SQL) |
  103. | `pnpm typecheck` | Run `tsc --noEmit` in every package |
  104. | `pnpm test` | Run the Vitest suites (see [Testing](#testing)) |
  105. | `pnpm build` | Build every package |
  106. | `pnpm verify` | Typecheck, test, and `pnpm audit --audit-level=high` |
  107. ## How the code is organized
  108. This is a pnpm workspace.
  109. | Path | What's there |
  110. |---|---|
  111. | [`apps/api`](apps/api) | The server (`@primer/api`): Hono on Node 24, Postgres through Drizzle, the REST API, the remote MCP endpoint, auth, and the companion script (`src/companion/v1.js`) that runs inside rendered documents. Migrations are in `apps/api/drizzle/`. |
  112. | [`apps/web`](apps/web) | The web app (`@primer/web`): React 19, React Router 7, TanStack Query, Tailwind 4, built with Vite. |
  113. | [`apps/mcp`](apps/mcp) | The stdio MCP server and login CLI, published to npm as [`@polygonlabs/primer-mcp`](https://www.npmjs.com/package/@polygonlabs/primer-mcp). |
  114. | [`packages/api-types`](packages/api-types) | The REST API's request and response types, published as `@polygonlabs/primer-api-types`. |
  115. | [`plugins/primer`](plugins/primer) | The Claude plugin: the `primer` skill and its MCP connection. [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) makes this repository a plugin marketplace. |
  116. | [`docs`](docs) | The product requirements (`docs/prd-primer.md`), and the design specs and implementation plans behind each feature (`docs/superpowers/`). |
  117. ## Configuration
  118. The API reads its settings from environment variables. In development it loads
  119. them from `.env`. [`.env.example`](.env.example) lists every option with notes.
  120. | Variable | Default | Purpose |
  121. |---|---|---|
  122. | `AUTH_MODE` | none, required | `mock` for local development (every request is a mock user; refused when `NODE_ENV=production`), or `okta` for real sign-in |
  123. | `DATABASE_URL` | none, required | Postgres connection string |
  124. | `DATABASE_URL_TEST` | none | Test database, used by `pnpm db:migrate:test` and the API tests |
  125. | `PORT` | `3000` | Port the API listens on |
  126. | `STORAGE_BACKEND` | `filesystem` | Where document content is stored: `filesystem` or `gcs` |
  127. | `STORAGE_ROOT` | `./storage` | Directory for the `filesystem` backend |
  128. | `GCS_BUCKET` | none | Bucket for the `gcs` backend, which authenticates with the environment's Google credentials |
  129. | `OKTA_ISSUER`, `OKTA_CLIENT_ID`, `OKTA_CLIENT_SECRET` | none | OpenID Connect client, required when `AUTH_MODE=okta` |
  130. | `AUTH_BASE_URL` | none | The public URL of your instance. Required when `AUTH_MODE=okta`; also used for sign-in redirects, links in emails, and secure cookies |
  131. | `OAUTH_ISSUER` | `AUTH_BASE_URL` | Issuer advertised to remote MCP clients |
  132. | `ADMIN_EMAILS` | none | Comma-separated admin emails. Admins can create service tokens, which act as a shared service account |
  133. | `SESSION_TTL_DAYS` | `14` | How long a browser session lasts |
  134. | `SESSION_COOKIE_NAME` | `primer_sid` | Session cookie name |
  135. | `COOKIE_SECURE` | from `AUTH_BASE_URL` | Force the cookie `Secure` flag |
  136. | `MAILGUN_API_KEY`, `EMAIL_FROM` | none | Email notifications through Mailgun. Without them, no email is sent. `MAILGUN_DOMAIN` and `MAILGUN_API_BASE_URL` are optional |
  137. | `SERVE_STATIC`, `STATIC_ROOT` | off | Serve the built web app from the API; the Docker image turns this on |
  138. | `LOG_LEVEL` | `info` | Log level |
  139. ## Running your own instance
  140. Primer ships as one Docker image: the API also serves the built web app, and
  141. the container applies database migrations before it starts. Build it from the
  142. repository root:
  143. ```bash
  144. docker build -f apps/api/Dockerfile -t primer .
  145. ```
  146. To run it, you need:
  147. - **Postgres** (Primer is developed against Postgres 17), set in `DATABASE_URL`.
  148. - **Storage for documents.** Use `STORAGE_BACKEND=gcs` with `GCS_BUCKET`, or
  149. the filesystem backend with `STORAGE_ROOT` on a persistent volume outside
  150. `/app`, which is read-only in the image.
  151. - **An OpenID Connect provider** for sign-in: `AUTH_MODE=okta` with the
  152. `OKTA_*` variables and `AUTH_BASE_URL`. Register
  153. `<AUTH_BASE_URL>/auth/callback` as the redirect URI. Primer uses standard
  154. OIDC discovery with the `openid profile email` scopes. It's built and run
  155. against Okta; other OIDC providers aren't tested.
  156. - `NODE_ENV=production`, set in the image, which rejects `AUTH_MODE=mock`.
  157. Optionally, set `ADMIN_EMAILS` to let admins create service tokens, and the
  158. Mailgun variables to send notification emails. `/api/health` and `/api/ready` are the
  159. liveness and readiness checks.
  160. Primer was built for one organization. Everyone who can sign in through your
  161. identity provider can see documents that are shared with the organization and
  162. the usage dashboard at `/admin`, and some text in the interface still says
  163. "Polygon".
  164. ## Testing
  165. The API tests run against a real Postgres database, `primer_test`, which
  166. `pnpm db:up` creates next to the development one. Before the first run, and
  167. after you pull new migrations, apply the schema:
  168. ```bash
  169. pnpm db:up
  170. pnpm db:migrate:test
  171. pnpm test
  172. ```
  173. Other test suites:
  174. - `pnpm --filter @primer/api test:browser` runs the companion script's
  175. consent-gate tests in a real headless Chrome, which you need installed. It
  176. isn't part of `pnpm test`; run it after changing `apps/api/src/companion/v1.js`.
  177. - `scripts/container-smoke.sh <db-host>` builds the Docker image, starts it,
  178. and runs the HTTP smoke tests against it, as the release pipeline does. It
  179. migrates the database it's given, so point it at a throwaway Postgres; the
  180. comment at the top of the script has the details.
  181. ## Contributing
  182. Issues and pull requests are welcome. Before you open a pull request:
  183. 1. Run `pnpm verify` (typecheck, tests and audit), or at least `pnpm typecheck`
  184. and `pnpm test`.
  185. 2. If your change affects a published package, the app, or the plugin, add a
  186. changeset with `pnpm changeset`, and describe the change for the people who
  187. use it. CI checks for one.
  188. 3. Commit any new migration that `pnpm db:generate` creates.
  189. CI runs the typecheck, build and tests on every pull request.
  190. **Dependencies are locked down on purpose.** `pnpm-workspace.yaml` won't
  191. install a package version less than 14 days old, allows install scripts only
  192. for packages on its `allowBuilds` list (just `esbuild` today), and blocks
  193. transitive dependencies installed from git, tarballs or URLs. Always install with
  194. `pnpm install --frozen-lockfile`. If you add a dependency that needs an
  195. install script or a newer version, explain why in the pull request.
  196. **Releases.** [Changesets](https://github.com/changesets/changesets) collects
  197. changesets into a "Version Packages" pull request. A maintainer merging it is
  198. the release: it publishes the npm packages and the plugin update, and tags the
  199. API version, which builds, tests and publishes the Docker image. See
  200. [`.github/workflows/release.yml`](.github/workflows/release.yml).
  201. ## Security
  202. Please don't report vulnerabilities in public issues. Follow Polygon's
  203. [security policy](https://github.com/0xPolygon/primer/security/policy) instead:
  204. use **Report a vulnerability** on this repository's Security tab, or the
  205. Polygon bug bounty programs listed there.
  206. ## License
  207. Copyright (c) 2026 PT Services DMCC
  208. Licensed under either:
  209. - Apache License, Version 2.0, ([LICENSE-APACHE](./LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>), or
  210. - MIT license ([LICENSE-MIT](./LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
  211. at your option.
  212. The SPDX license identifier for this project is `MIT` OR `Apache-2.0`.
  213. ## Contribution
  214. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.