"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." — Neal Stephenson, The Diamond Age
Primer is a place to publish HTML and Markdown documents, most often written by an LLM, at a stable URL, and to review them together. Upload a page (or have your agent publish it), share the link, and reviewers comment directly on the text. New versions keep the same URL, and the agent can pull the comments back in to write the next one.
Polygon builds Primer and runs it for its own teams. The code is open source under MIT or Apache-2.0, and you can run your own instance.
- What it does
- Publish from Claude and other agents
- Quickstart: run it locally
- How the code is organized
- Configuration
- Running your own instance
- Testing
- Contributing
- Security
- License
- Publishing. Upload a self-contained
.htmlfile or a.mdfile in the browser, or through the REST API and MCP tools. Markdown is rendered to HTML, with Mermaid diagrams supported. - Sandboxed rendering. Documents run in a sandboxed iframe. A small companion script inside the frame reports text selections and positions back to the app, so the document itself never touches your session.
- Anchored comments. Select text to start a thread on it. Threads support replies, mentions and email notifications.
- Versions. Each upload of a document is a new version at the same URL. You can switch between versions and see a diff between any two.
- Sharing. Documents are private to the owner and the collaborators they add (editor, responder or commenter), or visible to everyone in the organization. A published version can also be shared with people outside the organization, who sign in with a code sent to their email.
- Agent access. A remote MCP endpoint (
/mcp, OAuth 2.1), a stdio MCP server published to npm, and a REST API with scoped personal and service tokens. - Document events. Interactive documents can submit structured events (for example, a form answer), which the owner's tooling reads back over the API or a live stream. See the events loop guide.
This repository is also a Claude plugin marketplace. The primer plugin adds
a skill that knows how to publish, version and read comments, and it connects
to Polygon's hosted Primer. At Polygon, install it once in Claude Code:
/plugin marketplace add 0xPolygon/primer
/plugin install primer@primer
/reload-plugins
Then ask Claude to "publish this to Primer". The first time, it asks you to sign in through your browser.
To use your own instance instead, point any MCP client at its remote endpoint,
https://<your-host>/mcp, or run the stdio server
@polygonlabs/primer-mcp with PRIMER_API_URL set to your host.
apps/mcp/README.md lists the tools and the login flow.
You need:
- Node.js 24 (the version in
.nvmrc). - pnpm. Run
corepack enableonce (Corepack comes with Node), or install a recent pnpm (10 or later) any way you like. Either way, the pnpm version pinned inpackage.jsonis 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 :5173Open 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.
| 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) |
pnpm build |
Build every package |
pnpm verify |
Typecheck, test, and pnpm audit --audit-level=high |
This is a pnpm workspace.
| Path | What's there |
|---|---|
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/. |
apps/web |
The web app (@primer/web): React 19, React Router 7, TanStack Query, Tailwind 4, built with Vite. |
apps/mcp |
The stdio MCP server and login CLI, published to npm as @polygonlabs/primer-mcp. |
packages/api-types |
The REST API's request and response types, published as @polygonlabs/primer-api-types. |
plugins/primer |
The Claude plugin: the primer skill and its MCP connection. .claude-plugin/marketplace.json makes this repository a plugin marketplace. |
docs |
The product requirements (docs/prd-primer.md), and the design specs and implementation plans behind each feature (docs/superpowers/). |
The API reads its settings from environment variables. In development it loads
them from .env. .env.example lists every option with notes.
| Variable | Default | Purpose |
|---|---|---|
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 |
DATABASE_URL |
none, required | Postgres connection string |
DATABASE_URL_TEST |
none | Test database, used by pnpm db:migrate:test and the API tests |
PORT |
3000 |
Port the API listens on |
STORAGE_BACKEND |
filesystem |
Where document content is stored: filesystem or gcs |
STORAGE_ROOT |
./storage |
Directory for the filesystem backend |
GCS_BUCKET |
none | Bucket for the gcs backend, which authenticates with the environment's Google credentials |
OKTA_ISSUER, OKTA_CLIENT_ID, OKTA_CLIENT_SECRET |
none | OpenID Connect client, required when AUTH_MODE=okta |
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 |
OAUTH_ISSUER |
AUTH_BASE_URL |
Issuer advertised to remote MCP clients |
ADMIN_EMAILS |
none | Comma-separated admin emails. Admins can create service tokens, which act as a shared service account |
SESSION_TTL_DAYS |
14 |
How long a browser session lasts |
SESSION_COOKIE_NAME |
primer_sid |
Session cookie name |
COOKIE_SECURE |
from AUTH_BASE_URL |
Force the cookie Secure flag |
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 |
SERVE_STATIC, STATIC_ROOT |
off | Serve the built web app from the API; the Docker image turns this on |
LOG_LEVEL |
info |
Log level |
Primer ships as one Docker image: the API also serves the built web app, and the container applies database migrations before it starts. Build it from the repository root:
docker build -f apps/api/Dockerfile -t primer .To run it, you need:
- Postgres (Primer is developed against Postgres 17), set in
DATABASE_URL. - Storage for documents. Use
STORAGE_BACKEND=gcswithGCS_BUCKET, or the filesystem backend withSTORAGE_ROOTon a persistent volume outside/app, which is read-only in the image. - An OpenID Connect provider for sign-in:
AUTH_MODE=oktawith theOKTA_*variables andAUTH_BASE_URL. Register<AUTH_BASE_URL>/auth/callbackas the redirect URI. Primer uses standard OIDC discovery with theopenid profile emailscopes. It's built and run against Okta; other OIDC providers aren't tested. NODE_ENV=production, set in the image, which rejectsAUTH_MODE=mock.
Optionally, set ADMIN_EMAILS to let admins create service tokens, and the
Mailgun variables to send notification emails. /api/health and /api/ready are the
liveness and readiness checks.
Primer was built for one organization. Everyone who can sign in through your
identity provider can see documents that are shared with the organization and
the usage dashboard at /admin, and some text in the interface still says
"Polygon".
The API tests run against a real Postgres database, primer_test, which
pnpm db:up creates next to the development one. Before the first run, and
after you pull new migrations, apply the schema:
pnpm db:up
pnpm db:migrate:test
pnpm testOther test suites:
pnpm --filter @primer/api test:browserruns the companion script's consent-gate tests in a real headless Chrome, which you need installed. It isn't part ofpnpm test; run it after changingapps/api/src/companion/v1.js.scripts/container-smoke.sh <db-host>builds the Docker image, starts it, and runs the HTTP smoke tests against it, as the release pipeline does. It migrates the database it's given, so point it at a throwaway Postgres; the comment at the top of the script has the details.
Issues and pull requests are welcome. Before you open a pull request:
- Run
pnpm verify(typecheck, tests and audit), or at leastpnpm typecheckandpnpm test. - If your change affects a published package, the app, or the plugin, add a
changeset with
pnpm changeset, and describe the change for the people who use it. CI checks for one. - Commit any new migration that
pnpm db:generatecreates.
CI runs the typecheck, build and tests on every pull request.
Dependencies are locked down on purpose. pnpm-workspace.yaml won't
install a package version less than 14 days old, allows install scripts only
for packages on its allowBuilds list (just esbuild today), and blocks
transitive dependencies installed from git, tarballs or URLs. Always install with
pnpm install --frozen-lockfile. If you add a dependency that needs an
install script or a newer version, explain why in the pull request.
Releases. Changesets collects
changesets into a "Version Packages" pull request. A maintainer merging it is
the release: it publishes the npm packages and the plugin update, and tags the
API version, which builds, tests and publishes the Docker image. See
.github/workflows/release.yml.
Please don't report vulnerabilities in public issues. Follow Polygon's security policy instead: use Report a vulnerability on this repository's Security tab, or the Polygon bug bounty programs listed there.
Copyright (c) 2026 PT Services DMCC
Licensed under either:
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0), or
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
The SPDX license identifier for this project is MIT OR Apache-2.0.
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.