- Rust 77.1%
- TypeScript 16.6%
- Svelte 6%
- CSS 0.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| app | ||
| crates | ||
| dev | ||
| dist | ||
| docs | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| justfile | ||
| README.md | ||
| rust-toolchain.toml | ||
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-appinstalls thepigeonholebinary to~/.local/binand a desktop entry (so it shows up in your application launcher) and icon under~/.local/share.just app-devruns the real Tauri app against a runningpigeonholed(just install-servicefirst).just app-fakeruns the UI alone in a browser, against an in-memory fake service — nopigeonholedneeded; handy for UI work.just test-e2eruns 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 withPW_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_DISPLAYorDISPLAYin its own environment to launch the app (Ruling R3-8); a user service started from a login shell may not have it. Runsystemctl --user import-environment WAYLAND_DISPLAY DISPLAYafter logging in (or add it to your session startup), or set[notifications] open_commandto an absolute path ifpigeonholeisn't on the service'sPATH. The shipped unit setsPATH=%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
pigeonholedrestarts. An app started from a notification is launched withsystemd-run --user --scopeso it lives outside the service's cgroup; without a workingsystemd-run --userthe service starts it directly, and thensystemctl --user restart pigeonholedtakes the app with it. Start the app yourself (launcher orpigeonhole) 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=1itself before WebKitGTK starts, so this shouldn't happen; if you need the DMA-BUF renderer for some other reason, setWEBKIT_DISABLE_DMABUF_RENDERER=0yourself 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 pigeonholedto 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 IDwith 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.comThis 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.