No description
  • Rust 77.1%
  • TypeScript 16.6%
  • Svelte 6%
  • CSS 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-20 09:17:13 +02:00
app test(app): poll for the ingest usage events; avoid a stale assignment in the Outbox delete handler 2026-10-20 09:01:05 +02:00
crates feat: pigeonctl accounts set-server changes an account's IMAP/SMTP host or port 2026-10-20 09:17:12 +02:00
dev feat(imap): async-imap adapter with TLS, XOAUTH2, IDLE and MOVE fallback 2026-10-06 21:39:59 +02:00
dist fix(service): snooze rules, Open in its own scope, bounded hidden-text scan, Trash refusal 2026-10-07 15:48:33 +02:00
docs docs: record the M4 final-review fixes, pre-flight rulings R3/R4 and limitations 2026-10-20 00:28:37 +02:00
.gitignore feat(app): Tauri scaffold with a reconnecting socket bridge and desktop commands 2026-10-07 12:40:50 +02:00
Cargo.lock feat(compose): Markdown to HTML and plain-text MIME with fonts from config 2026-10-19 21:48:28 +02:00
Cargo.toml feat(app): Tauri scaffold with a reconnecting socket bridge and desktop commands 2026-10-07 12:40:50 +02:00
justfile fix(app): snooze/trash rules, ordered list refreshes, refresh max-wait, lint builds dist 2026-10-07 15:51:47 +02:00
README.md feat: pigeonctl accounts set-server changes an account's IMAP/SMTP host or port 2026-10-20 09:17:12 +02:00
rust-toolchain.toml feat: workspace scaffold and shared protocol types 2026-10-06 20:38:19 +02:00

Pigeonhole

Pigeonhole is an open-source, local-first email client for Linux. It runs entirely on your machine: a background service (pigeonholed) keeps a local copy of your IMAP and Gmail accounts in sync, and front-ends talk to it over a local API. Later milestones add AI tagging, urgency scores and summaries, a keyboard-first triage "ingest box", and a desktop app.

See docs/PROGRESS.md for milestone status and handoff notes.

Status

Milestone 1 (service foundation) is complete: the SQLite store, IMAP password and Gmail OAuth accounts with secrets in the Secret Service keyring, sync with IDLE, the Unix-socket API, the pigeonctl command-line client and a systemd user unit. CONDSTORE, XOAUTH2 and the Gmail extensions are not yet verified against a real Gmail account (see docs/imap-library-review.md).

Milestone 2 (AI pipeline) is complete: AI triage is available headless, through pigeonctl and desktop notifications — see "AI triage" below.

Milestone 3 (app shell) is complete: a Tauri + Svelte desktop app with the sidebar, Overview and Pile views, a reading view with threads, done/group/snooze/tags/urgency/block actions, spam review, the command palette, and notification Open — see "App" below.

Milestone 4 (compose and send) is complete: Markdown compose with reply, reply-all, forward, attachments and mailto:, drafts synced to the server, and an outbox that retries failed sends.

Build and test

Requires Rust (see rust-toolchain.toml), just, cargo-nextest and Docker (for the GreenMail test server).

just test               # unit tests (no network)
just greenmail-up       # start a local GreenMail IMAP/SMTP server
just test-integration   # all tests, including the ones that need GreenMail
just lint               # rustfmt + clippy

Install the service

just install-service                    # pigeonholed + systemd user unit, enabled and started
cargo install --path crates/pigeonctl   # the command-line client

Both land in ~/.cargo/bin. Check the service with systemctl --user status pigeonholed; logs: journalctl --user -u pigeonholed.

App

The desktop app (Tauri + Svelte) is a window onto pigeonholed; it has no mail logic of its own (spec §2).

Prerequisites: Node ≥ 20, pnpm, and the WebKitGTK/libsoup dev packages Tauri links against — webkit2gtk-4.1 and libsoup-3.0 (Arch: pacman -S webkit2gtk-4.1). Then:

just app-install   # pnpm install for the app
just install-app   # builds and installs ~/.local/bin/pigeonhole + a desktop entry
  • just install-app installs the pigeonhole binary to ~/.local/bin and a desktop entry (so it shows up in your application launcher) and icon under ~/.local/share.
  • just app-dev runs the real Tauri app against a running pigeonholed (just install-service first).
  • just app-fake runs the UI alone in a browser, against an in-memory fake service — no pigeonholed needed; handy for UI work.
  • just test-e2e runs the Playwright end-to-end tests against the fake service. They run in Chromium, not WebKitGTK (Playwright can't drive it — Ruling R3-15); the test uses the system Chromium (/usr/bin/chromium, override with PW_CHROMIUM), since the bundled-browser download is unavailable in this environment.

Keyboard shortcuts

Action Default keys
Next / previous message j / k, or ↓ / ↑
Open / back Enter / Esc
Done e
Move to group g
Snooze s
Edit tags t
Set urgency u
Not spam (Probably spam view) n
Trash Delete, #
Block sender b
Reply / reply all / forward / new email r / a / f / c (M4 — shown as a hint until then)
Overview ⇄ Pile Tab
Command palette and search Ctrl+K
Quick Look Space
Keyboard shortcuts (this list) ?

Single-key shortcuts never fire while focus is in a text field. The in-app ? dialog always shows the keys actually in effect, including any override below.

Remapping keys

Ruling R3-12: put a [keys] table in $XDG_CONFIG_HOME/pigeonhole/keys.toml (usually ~/.config/pigeonhole/keys.toml). Each entry replaces that action's default keys; list several keys separated by commas. Unknown actions or empty values are ignored with a console warning; if a key is claimed by two actions, the later one in the file wins.

# ~/.config/pigeonhole/keys.toml
[keys]
done = "d"
next = "j, ArrowDown"
palette = "Ctrl+p"

Action names: next prev open back done group snooze tags urgency not_spam trash block reply reply_all forward compose toggle_mode palette quick_look help.

Troubleshooting

  • The notification's Open button does nothing. The service needs WAYLAND_DISPLAY or DISPLAY in its own environment to launch the app (Ruling R3-8); a user service started from a login shell may not have it. Run systemctl --user import-environment WAYLAND_DISPLAY DISPLAY after logging in (or add it to your session startup), or set [notifications] open_command to an absolute path if pigeonhole isn't on the service's PATH. The shipped unit sets PATH=%h/.local/bin:%h/.cargo/bin:/usr/local/bin:/usr/bin; if you installed the unit before that line existed, reinstall it (just install-service) or add the line yourself.
  • The app closes when pigeonholed restarts. An app started from a notification is launched with systemd-run --user --scope so it lives outside the service's cgroup; without a working systemd-run --user the service starts it directly, and then systemctl --user restart pigeonholed takes the app with it. Start the app yourself (launcher or pigeonhole) to avoid that.
  • A blank window on some GPU/driver combinations. WebKitGTK's DMA-BUF renderer can crash with "Error 71 (Protocol error)" on some NVIDIA + Wayland setups. The app sets WEBKIT_DISABLE_DMABUF_RENDERER=1 itself before WebKitGTK starts, so this shouldn't happen; if you need the DMA-BUF renderer for some other reason, set WEBKIT_DISABLE_DMABUF_RENDERER=0 yourself to opt out of that default.
  • "The Pigeonhole service is not running." Click Start service in the app's banner, or run systemctl --user status pigeonholed to see why it isn't.

AI triage

New inbox mail can be tagged, scored for urgency, summarised and checked for phishing by an AI model you bring yourself (Anthropic, Ollama, or any OpenAI-compatible server). The rule-based threat checks, blocklist and unsubscribe extraction are part of the same per-message pipeline, so they need a classify model configured too — there is no AI triage of any kind without one. See docs/ai-setup.md for setup, what data is sent to a provider, and the full pigeonctl ai/triage command reference.

Configuration

~/.config/pigeonhole/config.toml (optional; every key has a default). It never contains account passwords, tokens or AI provider API keys; those live in the Secret Service keyring.

socket_path = "/run/user/1000/pigeonhole.sock"  # default: $XDG_RUNTIME_DIR/pigeonhole.sock
data_dir = "/home/me/.local/share/pigeonhole"   # default: $XDG_DATA_HOME/pigeonhole
idle_timeout_secs = 600                          # re-issue IDLE after this long
poll_interval_secs = 300                         # for servers without IDLE
credentials = "secret_service"                   # "memory" is for tests only

[gmail_oauth]                                    # your own Google OAuth "Desktop app" client
client_id = "1234-abc.apps.googleusercontent.com"
client_secret = "GOCSPX-..."

# [ai]                                            # AI triage (see docs/ai-setup.md); no defaults, opt-in
# backfill_days = 7                               # inbox mail older than this (before the first scan) is never analysed
# concurrency = 2                                 # parallel AI calls
# body_char_cap = 6000                            # plain-text body characters sent to a model
# corrections_in_prompt = 10                      # recent corrections shown to the classify model
#
# [ai.providers.claude]
# kind = "anthropic"                              # or "ollama" / "openai_compatible"
#
# [ai.tasks]
# classify  = { provider = "claude", model = "claude-opus-5", effort = "low" }
# summarise = { provider = "claude", model = "claude-opus-5", effort = "low" }
# # threat  = { provider = "claude", model = "claude-opus-5" }   # optional dedicated threat check
#
# [ai.prices."claude-opus-5"]                     # overrides/adds a cost-estimate entry
# input_per_mtok = 5.0
# output_per_mtok = 25.0

# [notifications]                                 # desktop notifications for urgent mail
# enabled = true
# threshold = 4                                   # notify at this urgency or higher (1..=5)
# quiet_hours = { start = "22:00", end = "07:00" } # local time, optional

# [compose]                                       # fonts in the HTML part of sent mail (the plain part is the Markdown)
# body_font = "-apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif"
# mono_font = "ui-monospace, 'JetBrains Mono', 'DejaVu Sans Mono', Menlo, Consolas, monospace"

A Gmail OAuth client in the config overrides the built-in one. Official builds get a built-in client from the build-time environment variables PIGEONHOLE_GMAIL_CLIENT_ID and PIGEONHOLE_GMAIL_CLIENT_SECRET (never committed). A local build without them has no Gmail client unless you configure [gmail_oauth].

pigeonctl reads socket_path and data_dir from the same file, so it always finds the service. --socket PATH or PIGEONHOLE_SOCKET override it.

Accounts

# IMAP with a password (prompted for, or taken from PIGEONHOLE_PASSWORD)
pigeonctl accounts add-imap --email me@example.org --host imap.example.org
# Gmail: opens your browser to sign in with Google
pigeonctl accounts add-gmail --email me@gmail.com
# List accounts with their state (synced, offline, auth error) and the reason
pigeonctl accounts list
# Replace the password of an IMAP account and retry it now
pigeonctl accounts set-password 3
# Change a server; options left out keep their value
pigeonctl accounts set-server 3 --smtp-host smtpout.secureserver.net
pigeonctl accounts remove 3

Other commands: folders ACCOUNT, ls FOLDER, show MESSAGE, search WORDS, flag, mv, sync, watch (stream events), triage, tags, block, unsub, outbox, drafts, ai (see docs/ai-setup.md for the AI-related commands). Add --json for raw output; see pigeonctl --help.

Sending (written in the app) can be inspected from the command line:

pigeonctl outbox            # queued, retrying, failed and recently sent mail, with the last error
pigeonctl outbox retry 12   # retry an outbox item now
pigeonctl drafts            # local drafts, most recently edited first

A failed send stays in the outbox with its error until you retry, edit or delete it. After a wrong SMTP password, fix it with pigeonctl accounts set-password ID, then retry. add-imap guesses the SMTP host from the IMAP host (imap.X becomes smtp.X) and prints it; if sends time out, the guess is probably wrong (GoDaddy, for example, uses smtpout.secureserver.net). Fix it with pigeonctl accounts set-server ID --smtp-host HOST: retrying items are sent right away. SMTP uses implicit TLS (port 465); STARTTLS is not supported yet.

When an account is broken

pigeonctl accounts list shows auth error: ... when the server or Google rejects the stored credentials. Network problems show as offline: ... and recover on their own.

  • IMAP account: run pigeonctl accounts set-password ID with the correct password.

  • Gmail account (for example after revoking access or changing your Google password): there is no re-authentication flow yet. Remove the account and add it again:

    pigeonctl accounts remove ID
    pigeonctl accounts add-gmail --email me@gmail.com
    

    This deletes the account's local copy and syncs it again from Gmail; nothing on the server changes. Local changes not yet sent to the server are lost.

License

GPL-3.0-or-later.