Postino Clipper — Browser Extension

Chrome MV3 extension that clips web content to your local Postino knowledge base. All data stays on your machine — the extension communicates exclusively with Postino's clipper server on localhost.

Features

• Right-click context menu — Save page, selection, or link to Postino
• Popup UI — Connection status, save current page, today's clip history
• YouTube integration — "Save to Postino" button injected next to Like/Share
• Twitter/X integration — Save button on every tweet, adapts to dark/light mode
• Rich metadata — Each clip includes source, author, channel, media URLs, timestamps
• Badge counter — Shows how many clips you've saved this session
• Clip history — View today's saved clips directly in the popup

Architecture

Browser Extension ──HTTP──► Postino Clipper Server (127.0.0.1:9090)
                              ├── GET  /health  (no auth)
                              └── POST /ingest  (X-Postino-Token)

Project Structure

├─�� shared/              # Constants, storage wrapper, API client
│   ├── constants.js
│   ├── storage.js
│   └── api.js
├── background/          # Service worker: context menus, message routing, badge
│   └── background.js
├── popup/               # Extension popup: pairing, status, save, history
│   ├── popup.html
│   ├── popup.js
│   └── popup.css
├── content/             # Platform-specific content scripts
│   ├── content.css
│   ├── youtube.js
│   ├── twitter.js
│   └── shared/          # Reusable content script modules
│       ├── button-factory.js
│       ├── messaging.js
│       └── toast.js
├── icons/               # Extension icons (generated from Postino SVG)
├── scripts/
│   └── build.mjs        # esbuild bundler + ZIP archiver
└── docs/
    └── postino-extension-req.md

Tech Stack

• Vanilla JavaScript (ES2021+) — no frameworks, no TypeScript
• Manifest V3 — Chrome extension standard
• esbuild — bundler (IIFE format, Chrome 110+ target)
• chrome.storage.local — token and settings (never synced)

Setup

# Install dependencies
npm install

# Build (outputs to dist/)
npm run build

# Watch mode (auto-rebuild on changes)
npm run watch

# Lint
npm run lint

Load in Chrome

1. Go to chrome://extensions/
2. Enable Developer mode
3. Click Load unpacked
4. Select the dist/ folder

Pairing with Postino

1. Open the Postino desktop app
2. Go to Settings > Clipper and copy the auth token
3. Click the Postino Clipper extension icon
4. Paste the token and click Connect

Configuration

• Port: Default 9090, configurable in extension settings. Falls back to 9091 automatically.
• Token: Stored locally, never synced. Disconnect from settings to clear.

Security

• All requests go to 127.0.0.1 only — never to external servers
• Token stored in chrome.storage.local (encrypted at rest by browser)
• No <all_urls> permission — uses activeTab + platform-specific matches
• Content Security Policy: script-src 'self'