Paperless Clipper

A Safari Web Extension for macOS and iOS/iPadOS that one-tap-saves the active webpage to a self-hosted Paperless-ngx server.

You share the page; classification (tags, correspondent, document type, refined title) happens server-side via Paperless's existing AI/classifier pipeline. There is no metadata UI on the save path.

Default view: one tap to save

Settings: server URL + API token

Install (macOS)

1. Download the latest .dmg from Releases.
2. Open the DMG and drag Paperless Clipper to Applications.
3. Launch the app once (Spotlight: "Paperless Clipper") so macOS registers the bundled extension.
4. Open Safari → Settings → Extensions and enable Paperless Clipper.
5. Get your Paperless API token: log in to your Paperless server in a browser, click the account dropdown in the top-right, choose My Profile, and copy the API Auth Token.
6. Click the leaf icon in the Safari toolbar → gear → enter your Paperless server URL and paste the token.
7. Click the leaf again on any page and tap Save current page.

The DMG is signed by Web Performance Incorporated and notarized by Apple, so no Gatekeeper warnings.

How it works

1. Capture: A content script runs Mozilla Readability on a clone of the active document, producing a clean reader-mode HTML article.
2. Render: The HTML is rendered locally to a paginated PDF via WKWebView.createPDF in the extension process.
3. Upload: The PDF is POSTed over HTTPS to your Paperless server's /api/documents/post_document/ endpoint with the page's source URL preserved in the title.

The whole pipeline runs on your device. The PDF and your API token never leave your network except to reach the Paperless server you configured.

Why there's no tag picker or title field

By design — and it's the feature, not a missing one. Modern Paperless-ngx ships with an AI/classifier pipeline that reads each ingested document and assigns a sensible title, tags, correspondent, and document type on its own. Watching it correctly categorize a stack of random PDFs and website clips, then write a useful title for each, is genuinely delightful — and it saves an enormous amount of the manual organizing work that usually surrounds a personal archive.

So the extension does the smallest thing it can: capture the page, send it to your server, and get out of the way. No metadata prompt, no tag picker, no title override. Whatever your Paperless instance is configured to do post-ingestion is what happens.

If you want different titles or tags than your server is choosing, fix it at the server (train the classifier, edit auto-matched tags, adjust workflows). The extension intentionally does not duplicate that surface.

Privacy

No telemetry, no third-party services, no phoning home. See PRIVACY.md.

Status

• macOS: working end-to-end. Released as a notarized DMG (Developer ID, signed by Web Performance Incorporated).
• iOS / iPadOS: working in the iPhone simulator with the same in-extension architecture as macOS. Real-device validation pending; no public iOS release yet.

Repository layout

• TypeScript Web Extension code: web/src/
• Swift containing-app code: apps/macOS/, apps/iOS/
• Swift code shared across targets: shared-swift/
• Native bridge (lives in the extension target): extension/SafariWebExtensionHandler.swift
• Build helper scripts: scripts/build-web.sh, scripts/release-macos.sh
• Spec, plan, tasks, research, contracts: live in the sibling repository under paperless-ngx/specs/001-safari-web-clipper/

Building from source

See SETUP.md for the one-time Xcode project setup, signing, and build configuration.

To produce a notarized release DMG, see the prerequisites at the top of scripts/release-macos.sh, then:

bash scripts/release-macos.sh

The output lands at build/release/PaperlessClipper-<version>.dmg.

License

TBD.