Proton Mail Bridge Agent Skill

Give coding agents read-only access to a Proton Mail inbox — with instant full-text search across the entire archive — through the local Proton Mail Bridge IMAP server.

The skill ships pmail, a zero-dependency Python CLI (stdlib only) that talks IMAP to Bridge on 127.0.0.1:1143, maintains a local SQLite+FTS5 cache of the whole mailbox, and serves bm25-ranked keyword search with snippets in well under a second (measured against an ~80k-message archive where Bridge's own server-side search takes ~15s and returns unranked UIDs).

Requirements

• macOS (credentials are stored in the system Keychain)
• Proton Mail Bridge installed, signed in, and running
• Python 3.9+ (no packages to install — stdlib only)

Install

Install with the Skills CLI:

npx skills add lukeramsden/protonmail-bridge-agent-skill@protonmail-bridge

Install globally for all supported agents:

npx skills add lukeramsden/protonmail-bridge-agent-skill@protonmail-bridge -g -a '*' -y

List the skills available in this repository without installing:

npx skills add lukeramsden/protonmail-bridge-agent-skill --list

Quick start

./doctor                              # verify all runtime dependencies
./pmail setup                         # account email + Bridge password -> Keychain
./pmail sync --all --full             # backfill the whole archive (resumable)
./pmail search "invoice"              # ranked full-text search, sub-second
./pmail search "INV-2026-00" --substring   # substring / attachment-name search
./pmail list INBOX --unseen
./pmail read 34655
./pmail save-attach 34655 1

All commands print JSON on stdout; progress and errors go to stderr. list and search return {mailbox, source, count, messages: [...]} — use jq '.messages[]' for the rows (full table in skills/protonmail-bridge/SKILL.md).

What the skill provides

• Full-archive FTS search — SQLite FTS5 with bm25 ranking and match snippets; phrases, OR/NOT, prefix *, and filters (--from, --since, --unseen, --mailbox)
• Substring search — --substring does a case-insensitive LIKE scan for partial tokens and attachment filenames/MIME types; metadata fields via a covering index (sub-second), bodies opt-in with --field body
• Resumable backfill — cursor-persisted batches; interrupt and resume freely; automatic wipe/resync if Bridge's UIDVALIDITY changes
• Cache-first reads — list, read, and search serve from the local cache with an implicit incremental sync at most once per minute; --live and --no-sync escape hatches
• Attachment download — save-attach extracts parts to the cache's attachments directory
• Self-diagnostics — doctor checks python/sqlite, credentials, Bridge reachability + login, cache health, and disk space, printing an actionable fix per failure
• Read-only by construction — only BODY.PEEK and EXAMINE on the wire; no STORE/COPY/EXPUNGE/APPEND anywhere, so reading mail never sets \Seen

Privacy and security

• Everything is local: pmail only ever connects to the Bridge listener on your own machine
• The Bridge password lives in macOS Keychain (service pmail-bridge); the only on-disk config is your account email in ~/.local/share/pmail/config.json (mode 600)
• The cache (~/.local/share/pmail/) is fully rebuildable — delete it anytime and re-run pmail sync --all --full

Repository layout

skills/
└── protonmail-bridge/
    ├── SKILL.md    # agent-facing instructions and command reference
    ├── pmail       # the CLI (Python stdlib only, executable)
    └── doctor      # runtime dependency checker

License

This repository is available under the MIT License. See NOTICE for trademark attribution.

Install as a pi package

pi install npm:protonmail-bridge-agent-skill

Releasing

npm version patch|minor|major && git push --follow-tags

The v* tag triggers .github/workflows/publish.yml, which publishes to npm with OIDC trusted publishing and provenance.