A fast, keyboard-driven Gmail client for the terminal, inspired by slk.
┌──┬──────────────────────────────────────────────┐
│YA│ inbox list (top pane) │
│PE│──────────────────────────────────────────────│
│ │ selected email (bottom pane) │
└──┴──────────────────────────────────────────────┘
accounts rail (like slk workspaces)
- CLI skeleton
- Add / list / remove Gmail accounts (OAuth 2.0 + PKCE, tokens in macOS Keychain)
- TUI: account rail, thread list, reading pane, status bar
- Conversations as an accordion: newest and unread messages open, others on one line; focus a message to reply to it
- Disk cache: instant startup, incremental sync (by thread historyId), prefetch
- Compose / reply / reply all / forward (in-app editor or
$EDITOR), save drafts - Signatures, one per account (plain text, see Config below)
- Attachments: attach files (
ctrl+abrowser or drag & drop), forward with attachments; 📎 on list rows - Archive / trash / star / mark unread, with undo, on one conversation or several (
x) - Labels sidebar
- Search (
/, Gmail search syntax) - Links & attachments picker (
o): open links, save/open attachments, copy links - Address autocomplete in To/Cc, learned from Sent mail and synced senders
- Near-instant sync: Gmail history polled every 10 s (≈2 quota units), plus on terminal focus
make install # tests, then builds to ~/.local/bin/pigeon (PREFIX=/usr/local to change)
make uninstall # removes the binary; config, Keychain tokens and cache are keptpigeon version prints the version (from git describe).
Changes go under ## [Unreleased] in CHANGELOG.md as they land. To release:
rename that section to ## [x.y.z] - YYYY-MM-DD, add an empty [Unreleased] above it and fix
the compare links at the bottom, commit, then git tag -a vx.y.z -m vx.y.z && git push --follow-tags.
Gmail scopes are "restricted", so pigeon uses an OAuth client you own (free, for personal use):
- https://console.cloud.google.com/ → create a project (e.g.
pigeon). - APIs & Services → Library → enable Gmail API.
- Google Auth Platform → Branding: fill in the app name and your email. Audience: External (or Internal if every account is in your Workspace org), then add each Gmail address you will use as a test user.
- Data Access → Add scopes →
https://www.googleapis.com/auth/gmail.modify. - Clients → Create client → type Desktop app → download the JSON.
pigeon setup ~/Downloads/client_secret_XXXX.json
⚠️ With an External app in Testing status, Google expires refresh tokens after 7 days, so you'd have to re-runpigeon account add. Use an Internal app (Workspace) or publish the app (unverified is fine for your own use; you'll click through a warning).
pigeon account add # opens the browser, pick the account
pigeon account add me@gmail.com # pre-select an account
pigeon account list --check # verify tokens against Gmail
pigeon account remove me@gmail.com # revoke at Google + delete from Keychain| Keys | Action |
|---|---|
j / k, ↓ / ↑ |
next / previous conversation (message when reading) |
J / K |
next / previous conversation, from anywhere |
enter l tab |
read the conversation (marks it read) |
enter l |
expand / collapse the focused message (when reading) |
E |
expand all messages / collapse all but the focused one (when reading) |
esc h q |
back to the list |
gg / G |
top / bottom (newest / oldest message when reading) |
space, ctrl+d / ctrl+u |
scroll the conversation (the focus follows) |
1–9, [ / ] |
switch account |
gi gs gt gd ga |
inbox, starred, sent, drafts, all mail |
e / # |
archive / move to trash |
s / u |
star / mark unread (toggles) |
x |
select / unselect the conversation; e # s u then act on all selected ones, esc clears |
z |
undo the last archive / trash (the whole batch) |
c |
compose a new message |
r / a / f |
reply / reply all / forward the focused message (the latest one unless you moved) |
ctrl+enter / ctrl+s |
send (in compose; ctrl+enter needs Ghostty, kitty, WezTerm…) |
ctrl+e |
edit the body in $EDITOR (in compose) |
tab / shift+tab |
next / previous field (in compose) |
↓ ↑ / ctrl+n ctrl+p, tab |
choose / accept an address suggestion (To, Cc) |
ctrl+a |
attach a file (in compose); dropping files on the terminal also attaches them |
esc |
close compose: save draft, discard, or keep editing |
/ |
search with Gmail syntax (from: subject: has:attachment after:2026/09/01 …); esc leaves the results |
o |
links & attachments of the conversation: enter open, s save to ~/Downloads (or $PIGEON_DOWNLOAD_DIR), y copy link, 1–9 pick |
U |
toggle unread only / all conversations (the inbox starts unread-only) |
ctrl+r |
sync now (changes also arrive within ~10 s); drops conversations read meanwhile from the unread view |
? |
help |
q q / ctrl+c |
quit (q asks first: q or y confirms, any other key stays) |
-
Attachment clip: the 📎 in front of a list row is guessed from each message's top-level MIME type (
multipart/mixed), the only hint in Gmail's cheapmetadataformat; a rare message without a real file (some calendar invites) can show it too. -
Theme: Catppuccin Mocha (
internal/tui/theme.go), colors mapped to the Catppuccin style guide roles; modes match LazyVim's lualine (NORMAL blue, INSERT green, READ mauve). No background is painted except selection and badges, so transparent terminals stay transparent. -
Go: single static binary, ~10 ms startup, and Bubble Tea for the upcoming TUI.
-
Scope
gmail.modify: read, compose, send, label, archive, trash (no permanent delete). -
Secrets: refresh tokens live in the OS keychain (service
pigeon), never on disk. Refreshed access tokens are written back automatically (auth.Client). -
Config:
~/.config/pigeon/($XDG_CONFIG_HOMErespected)credentials.json: OAuth client (0600)accounts.json: ordered account list (= rail order). Add"badge": "YF"to an account to pick its 2-letter rail badge instead of the computed one.signatures/<email>.txt: the account's signature, inserted verbatim under what you write (above the quote in replies and forwards). Start it with--(dash dash space) so mail clients recognize it. No file, no signature.
-
Contacts for autocomplete:
~/.cache/pigeon/<email>/contacts.json, built from the recipients of your last 500 sent emails (then incrementally) and the senders of synced mail. No Contacts API scope needed. -
Cache:
~/.cache/pigeon/<email>/($XDG_CACHE_HOMErespected), files 0600. First paint comes from disk (~1 ms); a sync re-downloads only threads whosehistoryIdchanged. -
Gmail REST is called directly over
net/http(no heavy generated SDK), so the binary stays small.