Higgs: local CLI for Proton Mail using local AI, no cloud or telemetry

Higgs is a CLI for Proton Mail designed from the ground up to be driven by language models rather than humans. The tool connects to Proton Mail Bridge (a local IMAP service) and streams each message through a local LLM running on Ollama or a compatible server such as llama.cpp llama-server. It applies labels from an 11-category taxonomy—all inference happens on localhost, with no API keys, cloud calls, or telemetry.

The core innovation is the agent contract. Instead of human-readable prose and ambiguous exit codes, every command outputs structured JSON. The schema manifest (higgs schema) returns a machine-readable description of every subcommand: flag types, argument names, stdout format (JSON or NDJSON), and exit codes. An agent loads this once and can drive the CLI without prompt engineering. Streaming commands emit one JSON object per line followed by a terminator record ({"type": "summary", ...}), so the agent knows when the stream is done. Every error emits a typed envelope with kind, code, reason, message, and hint—agents branch on the kind field (auth, config, imap, classify, state, etc.) rather than parsing English. Exit codes 0–9 map 1:1 to error kinds: 0 for success, 2 for auth failure, 3 for validation, 4 for config, 5 for IMAP protocol error, 6 for classification error, 7 for state DB error, and so on.

For the mail classifier workload, users export their Proton Mail Bridge IMAP username and password (stored in the OS keyring, not the shell), set the Ollama host and model (default: Gemma 4), and run higgs classify --dry-run --limit 20 INBOX. The tool emits NDJSON: each row contains the mailbox name, UID, subject, sender, suggested labels, confidence score, and a rationale. A summary record follows. If the suggestions look correct, rerun with --apply to write labels back. The tool supports flags for dry-run, concurrent workers (default: 4), and per-message limit. State is checkpointed in a local SQLite database, so runs are resumable after crashes. Commands compose over pipes: higgs search INBOX --before 2025-07-01 | higgs archive INBOX --uid - chains a search and archive. Other commands include scan-folders (enumerate mailboxes), cleanup-labels (consolidate legacy labels), backfill (replay a prior NDJSON log into the state DB), verify (audit a mailbox against an expected UID set), and state query (inspect per-message classification records without reconnecting to IMAP).

Credentials are stored in the OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service) or an encrypted file (~/.higgs/credentials.enc, AES-256-GCM with Argon2id keys). All configuration is read from environment variables: PM_IMAP_HOST, PM_IMAP_USERNAME, PM_IMAP_PASSWORD for Proton Mail Bridge; PM_OLLAMA_BASE_URL and PM_OLLAMA_MODEL for Ollama (default: http://localhost:11434 and gemma4). Alternatively, set PM_LLM_BACKEND=openai and point to a compatible self-hosted server such as llama.cpp or Qwen3. The tool is available via Homebrew (brew install higgs), go install, or built from source. It is an independent, community-built project not affiliated with or endorsed by Proton AG.

Higgs addresses a real friction point in AI agent development: most CLI tools were designed for human operators, with prose help text, English error messages, and 0/1 exit codes. Wiring them into an agent loop requires prompt engineering, natural-language parsing, and heuristics to detect completion. Higgs inverts the assumption—every design decision assumes the primary caller is a language model. The schema manifest lets an agent load the tool's interface once (flags, args, output format, exit codes) without parsing --help. NDJSON streaming with a typed terminator ("summary" record) means the agent knows when a stream ends without counting lines. Typed error envelopes (with kind, code, reason, message, hint) let the agent branch on error.kind rather than substring-matching English text. Exit codes 1–9 map 1:1 to error kinds, so retry and escalation become deterministic.

The first workload is a mail classifier built on Proton Mail Bridge (IMAP) and Ollama, but the contract is the point. This pattern—schema-first, agent-first output, deterministic errors and codes—is reusable for any CLI. For Proton Mail users specifically, Higgs offers local-only classification with no cloud inference, no API costs, and all credentials in the OS keyring. The tool's state is persisted in SQLite, making runs resumable after crashes, and commands pipe together, so you can chain discovery, search, classify, apply, and audit operations in a single shell pipeline.

No comments yet. Be the first to share your thoughts!