# 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](https://proton.me/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](https://proton.me/mail/bridge) installed, signed in, and running
- Python 3.9+ (no packages to install — stdlib only)

## Install

Install with the Skills CLI:

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

Install globally for all supported agents:

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

List the skills available in this repository without installing:

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

## Quick start

```bash
./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

```text
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](NOTICE) for trademark attribution.

## Install as a pi package

```bash
pi install npm:protonmail-bridge-agent-skill
```

## Releasing

```bash
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.