# higgs

> A private, local-first AI CLI for Proton Mail. Classification, search, summarization, and Q&A run entirely on the user's machine through Proton Mail Bridge and a local model — Ollama by default, or any self-hosted OpenAI-compatible server such as llama.cpp llama-server — no cloud inference, no cloud API keys, no telemetry. Agent-first by design: schema manifest for tool use, NDJSON on stdout, typed error envelopes, and a stable exit-code enum, with 30+ composable commands.

Privacy is the architecture, not a policy: Proton Mail users chose end-to-end encryption so nobody can exploit their mail, and piping messages to a cloud AI API would undo that in one request. higgs has no code path that sends a message anywhere except Proton Mail Bridge on 127.0.0.1 and a locally hosted model: Ollama by default (Gemma 4), or any self-hosted OpenAI-compatible server such as llama.cpp llama-server, selected with PM_LLM_BACKEND=openai (PM_OPENAI_API_KEY, if set, is only an optional bearer token for your own server — never a cloud account). Credentials live in the OS keyring (AES-256-GCM file fallback) and never enter a model's context. Zero telemetry; Apache-2.0 open source; cosign-signed releases with SBOM. higgs is an unofficial, independent project, not affiliated with, endorsed by, or sponsored by Proton AG. Output is always structured JSON on stdout (a single document, an NDJSON stream ending with a {"type":"summary"} terminator, or a typed error envelope), never prose. Exit codes 0–9 map 1:1 to error kinds so retry and escalation are deterministic. Commands compose over pipes: any command that accepts --uid also accepts --uid -, reading UIDs (plain or NDJSON) from stdin.

## Docs

- [Full site content](https://higgscli.com/llms-full.txt): The complete plain-text description of higgs, including the agent contract, command list, install steps, configuration, and exit codes.
- [Homepage](https://higgscli.com): The higgs website.
- [Source, README, and issues](https://github.com/higgscli/higgs): The full project documentation and source code on GitHub.

## Setup for agents

- [Discover the tool](https://higgscli.com/llms-full.txt): Run `higgs schema` (or `higgs schema <command>`) to load a JSON manifest of every subcommand — flags, args, stdout format, exit codes — instead of parsing --help.
- [Read streams safely](https://higgscli.com/llms-full.txt): Streaming commands emit NDJSON and always end with one {"type":"summary", ...} line. Read until the terminator.
- [Recover from errors](https://higgscli.com/llms-full.txt): Failures emit {"error": {"kind", "code", "reason", "message", "hint"}}. Branch on .error.kind and the exit code, not on message text.

## Optional

- [Releases](https://github.com/higgscli/higgs/releases): Signed release binaries (cosign, SBOM included) for macOS, Linux, and Windows.
- [Homebrew tap](https://github.com/higgscli/homebrew-higgs): `brew tap higgscli/higgs && brew install higgs`.
- [Proton Mail Bridge](https://proton.me/mail/bridge): The official Proton bridge that higgs connects to over local IMAP.
- [Ollama](https://ollama.com): The default local model runtime for classify, ask, summarize, digest, and extract. higgs can instead target any self-hosted OpenAI-compatible server (e.g. llama.cpp llama-server) via PM_LLM_BACKEND=openai — still local-only.
- [Author](https://akeemjenkins.com): Akeem Jenkins, who designed and built higgs.