+2 -1

.claude/settings.local.json

reviewed

··· 10 10 "Bash(hugo version:*)", 11 11 "Bash(hugo mod graph:*)", 12 12 "Bash(make docs-sync:*)", 13 13 - "WebFetch(domain:raw.githubusercontent.com)" 13 13 + "WebFetch(domain:raw.githubusercontent.com)", 14 14 + "Bash(./scripts/sync-readme-to-docs.sh:*)" 14 15 ] 15 16 } 16 17 }

+11 -11

README.md

reviewed

··· 131 131 132 132 On first run, neomd: 133 133 1. Creates `~/.config/neomd/config.toml` with placeholders — fill in your IMAP/SMTP credentials 134 134 - - Important: Make sure that the Capitalization and naming of folder in `config.toml` is accroding to webmail IMAP, e.g. [Gmails](docs/gmail.md) uses `sent = "[Gmail]/Sent Mail"` and not `sent` etc. 134 134 + - Important: Make sure that the Capitalization and naming of folder in `config.toml` is accroding to webmail IMAP, e.g. [Gmails](docs/content/docs/configurations/gmail.md) uses `sent = "[Gmail]/Sent Mail"` and not `sent` etc. 135 135 2. Creates `~/.config/neomd/lists/` for screener allowlists (or uses your custom paths from config) 136 136 3. Creates any missing IMAP folders (ToScreen, Feed, PaperTrail, etc.) automatically 137 137 138 138 139 139 - Neomd also runs on Android (more for fun) — see [docs/android.md](docs/android.md). 139 139 + Neomd also runs on Android (more for fun) — see [docs/content/docs/configurations/android.md](docs/content/docs/android.md). 140 140 141 141 ## Configuration 142 142 ··· 166 166 167 167 Use an app-specific password (Gmail, Fastmail, Hostpoint, etc.) rather than your main account password. The `password` and `user` fields support environment variable expansion (`$VAR` or `${VAR}`) so you can avoid storing secrets in the config file. 168 168 169 169 - For the full configuration reference including multiple accounts, OAuth2 authentication, `[[senders]]` aliases, folder customization, signatures, and UI options, see [docs/configuration.md](docs/configuration.md). 169 169 + For the full configuration reference including multiple accounts, OAuth2 authentication, `[[senders]]` aliases, folder customization, signatures, and UI options, see [docs/content/docs/configuration.md](docs/content/docs/configuration.md). 170 170 171 171 **Provider-specific guides:** 172 172 - - Gmail: [docs/gmail.md](docs/gmail.md) — folder name mapping and OAuth2 setup 173 173 - - Proton Mail Bridge: [docs/proton-bridge.md](docs/proton-bridge.md) — non-standard port configuration 172 172 + - Gmail: [docs/content/docs/configurations/gmail.md](docs/content/docs/configurations/gmail.md) — folder name mapping and OAuth2 setup 173 173 + - Proton Mail Bridge: [docs/content/docs/configurations/proton-bridge.md](docs/content/docs/configurations/proton-bridge.md) — non-standard port configuration 174 174 175 175 ### Onboarding 176 176 ··· 201 201 202 202 ### Screener Workflow 203 203 204 204 - Find full Screener Workflow at [docs/screener.md](docs/screener.md), classification tables, and bulk re-classification instructions. 204 204 + Find full Screener Workflow at [docs/content/docs/screener.md](docs/content/docs/screener.md), classification tables, and bulk re-classification instructions. 205 205 ### Keybindings 206 206 207 207 Press `?` inside neomd to open the interactive help overlay. Start typing to filter shortcuts. 208 208 209 209 - See the [full keybindings reference](docs/keybindings.md) (auto-generated from [`internal/ui/keys.go`](internal/ui/keys.go) via `make docs`). 209 209 + See the [full keybindings reference](docs/content/docs/keybindings.md) (auto-generated from [`internal/ui/keys.go`](internal/ui/keys.go) via `make docs`). 210 210 211 211 ### How Sending Works 212 212 ··· 214 214 215 215 Discarding unsent mail now asks for confirmation in compose/pre-send, and `:recover` reopens the latest backup if you want to resume after an abort. 216 216 217 217 - - See [docs/sending.md](docs/sending.md) for details on MIME structure, attachments, pre-send review, and drafts. 218 218 - - See [docs/reading.md](docs/reading.md) for the reader: images, inline links, attachments, and navigation. 217 217 + - See [docs/content/docs/sending.md](docs/content/docs/sending.md) for details on MIME structure, attachments, pre-send review, and drafts. 218 218 + - See [docs/content/docs/reading.md](docs/content/docs/reading.md) for the reader: images, inline links, attachments, and navigation. 219 219 220 220 ### Dev: Makefile Commands 221 221 ··· 278 278 279 279 280 280 > [!NOTE] 281 281 - > **Gmail is not recommended.** If you're on Gmail, consider a dedicated email provider (Hostpoint, Fastmail, HEY, Migadu, etc.) for the best neomd experience. Or use Gmail just for fun :). See [docs/gmail.md](docs/gmail.md) for Gmail-specific folder configuration. 281 281 + > **Gmail is not recommended.** If you're on Gmail, consider a dedicated email provider (Hostpoint, Fastmail, HEY, Migadu, etc.) for the best neomd experience. Or use Gmail just for fun :). See [docs/content/docs/configurations/gmail.md](docs/content/docs/configurations/gmail.md) for Gmail-specific folder configuration. 282 282 283 283 **Test your own provider:** 284 284 ```bash ··· 311 311 312 312 I used my experience with Neomutt, TUIs, and the GTD workflow for handling emails with HEY Screener, and added some (hopefully) _taste_ using my favorite tools and aesthetics. Find the full history at [Twitter](https://xcancel.com/sspaeti/status/2036539855182627169#m) - inspired by seeing [Email.md](https://www.emailmd.dev/) on HackerNews. 313 313 314 314 - If you [rather read the prompt](https://www.ssp.sh/brain/id-rather-read-the-prompt), check out my [initial prompt](docs/initial-prompt/prompt.md) and its generated [plan](docs/initial-prompt/prompt-plan.md) - which I have iterated and added features by the 100s since then. 314 314 + If you [rather read the prompt](https://www.ssp.sh/brain/id-rather-read-the-prompt), check out my [initial prompt](https://github.com/ssp-data/neomd/blob/main/docs/initial-prompt/prompt.md) and its generated [plan](https://github.com/ssp-data/neomd/blob/main/docs/initial-prompt/prompt-plan.md) - which I have iterated and added features by the 100s since then. 315 315 ## Roadmap 316 316 317 317 See at my second brain at [Roadmap](https://www.ssp.sh/brain/neomd#roadmap).

+3 -3

docs/content/_index.md

reviewed

··· 17 17 </div> 18 18 19 19 <div class="hx-mb-6"> 20 20 - {{< hextra/hero-button text="Overview and Philosophy" link="docs/overview" >}} 20 20 + {{< hextra/hero-button text="Overview and Philosophy" link="docs" >}} 21 21 </div> 22 22 23 23 <div class="hx-mt-6"></div> ··· 80 80 </div> 81 81 82 82 {{< cards cols="3" >}} 83 83 - {{< card link="docs/overview" title="Overview & Philosophy" subtitle="Full feature list, installation (binary, AUR, source), philosophy, benchmarks, and inspiration" >}} 83 83 + {{< card link="docs" title="Overview & Philosophy" subtitle="Full feature list, installation (binary, AUR, source), philosophy, benchmarks, and inspiration" >}} 84 84 {{< card link="docs/configuration" title="Configuration Reference" subtitle="Full config with multiple accounts, OAuth2, signatures, and UI options" >}} 85 85 {{< card link="docs/keybindings" title="Keybindings" subtitle="Complete keyboard shortcuts reference (auto-generated from source)" >}} 86 86 {{< card link="docs/screener" title="Screener Workflow" subtitle="How to classify emails, bulk operations, and screener lists" >}} ··· 91 91 <br> 92 92 93 93 <div class="hx-mb-6"> 94 94 - {{< hextra/hero-button text="Getting Started: Install" link="docs/overview#install" >}} 94 94 + {{< hextra/hero-button text="Getting Started: Install" link="docs#install" >}} 95 95 </div> 96 96 97 97

+329 -2

docs/content/docs/_index.md

reviewed

··· 1 1 --- 2 2 - title: Documentation 2 2 + title: Overview & Philosophy 3 3 + weight: 0 3 4 --- 4 5 5 5 - Welcome to the neomd documentation. 6 6 + A minimal terminal email client for people who write in Markdown and live in Neovim. 7 7 + 8 8 + [Neomd](https://www.ssp.sh/brain/neomd/) is my way of implementing an email TUI based on my experience with Neomutt, focusing on [Neovim](https://www.ssp.sh/brain/neovim) (input) and reading/writing in [Markdown](https://www.ssp.sh/brain/markdown) and navigating with [Vim Motions](https://www.ssp.sh/brain/vim-language-and-motions) with the GTD workflow and [HEY-Screener](https://www.hey.com/features/the-screener/). 9 9 + 10 10 + 11 11 + {{< callout type="warning" >}} 12 12 + neomd moves, deletes, and modifies emails directly on your IMAP server. These operations affect your mailbox across all devices. **Back up important emails before first use.** neomd is experimental software and can't take responsibility for lost or misplaced emails. Consider testing with a secondary email account first. 13 13 + {{< /callout >}} 14 14 + 15 15 + 16 16 + ## The philosophy behind Neomd: What's unique? 17 17 + 18 18 + The key here is **speed** in which you can **navigate, read, and process** your email. Everything is just a shortcut away, and instantly (ms not seconds). It's similar to the foundations that Superhuman was built on: it runs on Gmail and makes it fast with vim commands. 19 19 + 20 20 + With the **HEY-Screener**, you get only emails in your inbox that you _screened in_, no spam or sales pitch before you added them. Or don't like them, just screen them out, and they get automatically moved to the "ScreenedOut" folder. 21 21 + 22 22 + With the [GTD approach](https://www.ssp.sh/brain/getting-things-done-gtd), using folders such as next (inbox), waiting, someday, scheduled, or archive, you can move them with one shortcut. This allows you quickly to move emails you need to wait for, or deal with later, in the right category. **Processing your email only once**. 23 23 + 24 24 + With the additional **Feed** and **Papertrail**, two additional features from HEY, you can read newsletters (just hit F) on them automatically in their separate tab, or move all your receipts into the Papertrail. Once you mark them as feed or papertrail, they will moved there automatically going forward. So you decide whether to read emails or news by jumping to different tabs. 25 25 + 26 26 + 27 27 + {{< callout type="info" >}} 28 28 + neomd's **speed** depends entirely on your IMAP provider. On Hostpoint (the provider I use), a folder switch takes **~33ms** which feels instant. On Gmail, the same operation takes **~570ms** which is noticeably slow. See [Benchmark](#benchmark) for full details and how to test your provider. 29 29 + {{< /callout >}} 30 30 + 31 31 + 32 32 + ## Screenshots 33 33 + 34 34 + ### Overview: List-View 35 35 + 36 36 + Feed view with all Newsletters - also workflow with differnt tabs and unread counter only for certain tabs (not all): 37 37 +  38 38 + 39 39 + ### Reading Panel 40 40 + 41 41 + Reading an email with Markdown 💙: 42 42 + 43 43 +  44 44 + 45 45 + ### Sent emails 46 46 + This is the markdown sent: 47 47 + 48 48 + ```markdown 49 49 + # [neomd: to: email@domain.com] 50 50 + # [neomd: subject: this is an email from neomd!] 51 51 + 52 52 + This email is from Neomd. Great I can add links such as [this](https://ssp.sh) with plain Markdown. 53 53 + 54 54 + E.g. **bold** or _italic_. 55 55 + 56 56 + ## Does headers work too? 57 57 + 58 58 + this is a text before a h3. 59 59 + 60 60 + ### H3 header 61 61 + 62 62 + how does that look in an email? 63 63 + Best regards 64 64 + ``` 65 65 + 66 66 + *Compose emails in your editor, read them rendered with [glamour](https://github.com/charmbracelet/glamour), and manage your inbox with a [HEY-style screener](https://www.hey.com/features/the-screener/) — all from the terminal.* 67 67 + 68 68 + 69 69 + Which looks like this: 70 70 + 71 71 +  72 72 + 73 73 + Or in Gmail: 74 74 +  75 75 + 76 76 + 77 77 + ### Video 78 78 + 79 79 + YouTube rundown of most features: 80 80 + [](https://youtu.be/8aKkldYLWV8) 81 81 + *(shorter but limited showcase [part 1 video](https://youtu.be/lpmHqIrCC-w))* 82 82 + 83 83 + 84 84 + ## Features 85 85 + 86 86 + - **Write in Markdown, send beautifully** — compose in `$EDITOR` (defaults to `nvim`), send as `multipart/alternative`: raw Markdown as plain text + goldmark-rendered HTML so recipients get clickable links, bold, headers, inline code, and code blocks 87 87 + - **Pre-send review** — after closing the editor, review To/Subject/body before sending; attach files, save to Drafts, or re-open the editor — no accidental sends 88 88 + - **Attachments** — attach files from the pre-send screen via yazi (`a`); images appear inline in the email body, other files as attachments; also attach from within neovim via `<leader>a`; the reader lists all attachments (including inline images) and `1`–`9` downloads and opens them 89 89 + - **Link opener** — links in emails are numbered `[1]`-`[0]` in the reader header; press `space+digit` to open in `$BROWSER` 90 90 + - **CC, BCC, Reply-all** — optional Cc/Bcc fields (toggle with `ctrl+b`); `R` in the reader replies to sender + all CC recipients 91 91 + - **Emoji reactions** — press `ctrl+e` from inbox or reader to react with emoji (👍 ❤️ 😂 🎉 🙏 💯 👀 ✅); instant send with proper threading and quoted message history, no editor needed; reactions appear in conversation threads with neomd branding 92 92 + - **Drafts** — `d` in pre-send saves to Drafts (IMAP APPEND); `E` in the reader re-opens a draft as an editable compose; compose sessions are auto-backed up to `~/.cache/neomd/drafts/` so you never lose an unsent email (`:recover` to reopen) 93 93 + - **HTML signatures** — configure separate text and HTML signatures; text signature appears in editor and plain text part, HTML signature in HTML part only; use `[html-signature]` placeholder to control inclusion per-email 94 94 + - **Multiple From addresses** — define SMTP-only `[[senders]]` aliases (e.g. `s@ssp.sh` through an existing account); cycle with `ctrl+f` in compose and pre-send; sent copies always land in the Sent folder 95 95 + - **Undo** — `u` reverses the last move or delete (`x`, `A`, `M*`) using the UIDPLUS destination UID 96 96 + - **Search** — `/` filters loaded emails in-memory; `space /` or `:search` runs IMAP SEARCH across all folders (only fetching header capped at 100 per folder) with results in a temporary "Search" tab; supports `from:`, `subject:`, `to:` prefixes 97 97 + - **Address autocomplete** — To/Cc/Bcc fields autocomplete from screener lists; navigate with `ctrl+n`/`ctrl+p`, accept with `tab` 98 98 + - **Everything view** — `ge` or `:everything` shows the 50 most recent emails across all folders; find emails that were screened out, moved to spam, or otherwise hard to locate 99 99 + - **Threaded inbox** — related emails are grouped together in the inbox list with a vertical connector line (`│`/`╰`), Twitter-style; threads are detected via `In-Reply-To`/`Message-ID` headers with a subject+participant fallback; newest reply on top, root at bottom; `·` reply indicator shows which emails you've answered 100 100 + - **Conversation view** — `T` or `:thread` shows the full conversation across folders (Inbox, Sent, Archive, etc.) in a temporary tab with `[Folder]` prefix; see your replies alongside received emails 101 101 + - **Glamour reading** — incoming emails rendered as styled Markdown in the terminal 102 102 + - **HEY-style screener** — unknown senders land in `ToScreen`; press `I/O/F/P` to approve, block, mark as Feed, or mark as PaperTrail; reuses your existing `screened_in.txt` lists from neomutt 103 103 + - **Folder tabs** — Inbox, ToScreen, Feed, PaperTrail, Archive, Waiting, Someday, Scheduled, Sent, Trash, ScreenedOut 104 104 + - **Multi-select** — `m` marks emails, then batch-delete, move, or screen them all at once 105 105 + - **Auto-screen on load** — screener runs automatically every time the Inbox loads (startup, `R`); keeps your inbox clean without pressing `S` (configurable, on by default) 106 106 + - **Background sync** — while neomd is open, inbox is fetched and screened every 5 minutes in the background; interval configurable, set to `0` to disable 107 107 + - **Kanagawa theme** — colors from the [kanagawa.nvim](https://github.com/rebelot/kanagawa.nvim) palette 108 108 + - **IMAP + SMTP** — direct connection via RFC 6851 MOVE, no local sync daemon required and keeps it in sync if you use it on mobile or different device 109 109 + 110 110 + ## Install 111 111 + 112 112 + **Prerequisites:** [Go 1.22+](https://go.dev/doc/install) and `make`. 113 113 + 114 114 + {{< callout type="info" >}} 115 115 + **Optional attachment helpers:** 116 116 + - `yazi` enables the built-in file picker used by pre-send `a` 117 117 + - custom Neovim integration in `custom.lua` enables inline `<leader>a` attachment insertion inside `neomd-*.md` buffers 118 118 + - without these, neomd still works; the inline Neovim attachment workflow just won't be available 119 119 + {{< /callout >}} 120 120 + 121 121 + 122 122 + ```sh 123 123 + git clone https://github.com/ssp-data/neomd 124 124 + cd neomd 125 125 + make install # installs to ~/.local/bin/neomd 126 126 + ``` 127 127 + 128 128 + Or just build locally: 129 129 + 130 130 + ```sh 131 131 + make build 132 132 + ./neomd 133 133 + ``` 134 134 + 135 135 + Or if on Arch Linux (AUR), you can use my [neomd-bin](https://aur.archlinux.org/packages/neomd-bin) via: 136 136 + ```sh 137 137 + yay -S neomd-bin 138 138 + ``` 139 139 + 140 140 + 141 141 + On first run, neomd: 142 142 + 1. Creates `~/.config/neomd/config.toml` with placeholders — fill in your IMAP/SMTP credentials 143 143 + - Important: Make sure that the Capitalization and naming of folder in `config.toml` is accroding to webmail IMAP, e.g. [Gmails](docs/content/docs/configurations/gmail.md) uses `sent = "[Gmail]/Sent Mail"` and not `sent` etc. 144 144 + 2. Creates `~/.config/neomd/lists/` for screener allowlists (or uses your custom paths from config) 145 145 + 3. Creates any missing IMAP folders (ToScreen, Feed, PaperTrail, etc.) automatically 146 146 + 147 147 + 148 148 + Neomd also runs on Android (more for fun) — see [docs/content/docs/configurations/android.md](docs/content/configurations/android). 149 149 + 150 150 + ## Configuration 151 151 + 152 152 + On first run, neomd creates `~/.config/neomd/config.toml` with placeholders: 153 153 + 154 154 + ```toml 155 155 + [[accounts]] 156 156 + name = "Personal" 157 157 + imap = "imap.example.com:993" # :993 = TLS, :143 = STARTTLS 158 158 + smtp = "smtp.example.com:587" 159 159 + user = "me@example.com" 160 160 + password = "app-password" 161 161 + from = "Me <me@example.com>" 162 162 + starttls = false 163 163 + tls_cert_file = "" # optional PEM cert/CA for self-signed local bridges 164 164 + 165 165 + # Root-level settings 166 166 + store_sent_drafts_in_sending_account = false # default: Sent/Drafts use first account; true = follow sending account 167 167 + 168 168 + [screener] 169 169 + screened_in = "~/.config/neomd/lists/screened_in.txt" 170 170 + screened_out = "~/.config/neomd/lists/screened_out.txt" 171 171 + feed = "~/.config/neomd/lists/feed.txt" 172 172 + papertrail = "~/.config/neomd/lists/papertrail.txt" 173 173 + spam = "~/.config/neomd/lists/spam.txt" 174 174 + ``` 175 175 + 176 176 + Use an app-specific password (Gmail, Fastmail, Hostpoint, etc.) rather than your main account password. The `password` and `user` fields support environment variable expansion (`$VAR` or `${VAR}`) so you can avoid storing secrets in the config file. 177 177 + 178 178 + For the full configuration reference including multiple accounts, OAuth2 authentication, `[[senders]]` aliases, folder customization, signatures, and UI options, see [docs/content/configuration](docs/content/configuration). 179 179 + 180 180 + **Provider-specific guides:** 181 181 + - Gmail: [docs/content/docs/configurations/gmail.md](docs/content/docs/configurations/gmail.md) — folder name mapping and OAuth2 setup 182 182 + - Proton Mail Bridge: [docs/content/docs/configurations/proton-bridge.md](docs/content/docs/configurations/proton-bridge.md) — non-standard port configuration 183 183 + 184 184 + ### Onboarding 185 185 + 186 186 + On first launch, **auto-screening is paused** because your screener lists are empty — neomd won't move anything until you've classified your first sender. Your Inbox loads normally so you can explore. 187 187 + 188 188 + By default, neomd loads and auto-screens only the newest `200` Inbox emails (`[ui].inbox_count`). This keeps startup predictable. If you want to re-screen the entire Inbox on the IMAP server, run `:screen-all` inside neomd; that scans every Inbox email, not just the loaded subset, and can take a while on large mailboxes. 189 189 + 190 190 + **Getting started with the screener:** 191 191 + 192 192 + 1. From your Inbox, pick an email and press `I` (screen **in**) to approve the sender, or `O` (screen **out**) to block them. This creates your first screener list entry. 193 193 + 2. Once you've classified at least one sender, auto-screening activates on every Inbox load — new emails from known senders are sorted automatically. 194 194 + 3. Unknown senders land in the `ToScreen` tab. Jump there with `gk` (or `Tab`, use `L` or click the tab) and classify them: 195 195 + - `I` screen **in** — sender stays in Inbox forever 196 196 + - `O` screen **out** — sender never reaches Inbox again 197 197 + - `F` **feed** — newsletters go to the Feed tab 198 198 + - `P` **papertrail** — receipts go to the PaperTrail tab 199 199 + 4. Use `m` to mark multiple emails, then `I` to batch-approve them all at once. From the `ToScreen` folder, approving/blocking a single unmarked message now applies to all currently queued mail from that sender. 200 200 + 201 201 + **The best part:** all classifications are saved permanently in your screener lists (`screened_in.txt`, `screened_out.txt`, etc.). An email address screened in will automatically go to your Inbox, and any email screened out will never be in your Inbox again. 202 202 + 203 203 + You choose who can land in your Inbox. Bye-bye spam. This is the beauty of [HEY-Screener](https://www.hey.com/features/the-screener/), and neomd implements the same concept. 204 204 + 205 205 + {{< callout type="info" >}} 206 206 + To disable auto-screening entirely, set `auto_screen_on_load = false` in `[ui]` config. Run `:debug` inside neomd if something isn't working. 207 207 + {{< /callout >}} 208 208 + 209 209 + 210 210 + {{< callout type="warning" >}} 211 211 + `:screen-all` operates on the full Inbox mailbox on the server, not just the emails currently loaded in the UI. Use it when you intentionally want a mailbox-wide reclassification pass. 212 212 + {{< /callout >}} 213 213 + 214 214 + 215 215 + ### Screener Workflow 216 216 + 217 217 + Find full Screener Workflow at [docs/content/screener](docs/content/screener), classification tables, and bulk re-classification instructions. 218 218 + ### Keybindings 219 219 + 220 220 + Press `?` inside neomd to open the interactive help overlay. Start typing to filter shortcuts. 221 221 + 222 222 + See the [full keybindings reference](docs/content/keybindings) (auto-generated from [`internal/ui/keys.go`](internal/ui/keys.go) via `make docs`). 223 223 + 224 224 + ### How Sending Works 225 225 + 226 226 + Compose in Markdown, send as `multipart/alternative` (plain text + HTML). Attachments, CC/BCC, multiple From addresses, drafts, and pre-send review are all supported. 227 227 + 228 228 + Discarding unsent mail now asks for confirmation in compose/pre-send, and `:recover` reopens the latest backup if you want to resume after an abort. 229 229 + 230 230 + - See [docs/content/sending](docs/content/sending) for details on MIME structure, attachments, pre-send review, and drafts. 231 231 + - See [docs/content/reading](docs/content/reading) for the reader: images, inline links, attachments, and navigation. 232 232 + 233 233 + ### Dev: Makefile Commands 234 234 + 235 235 + ``` 236 236 + make build compile ./neomd 237 237 + make run build and run 238 238 + make install install to ~/.local/bin 239 239 + make test run tests 240 240 + make vet go vet 241 241 + make fmt gofmt -w . 242 242 + make tidy go mod tidy 243 243 + make clean remove compiled binary 244 244 + make help print this list 245 245 + ``` 246 246 + 247 247 + ## Stack 248 248 + 249 249 + - [Bubble Tea](https://github.com/charmbracelet/bubbletea) — TUI framework 250 250 + - [Bubbles](https://github.com/charmbracelet/bubbles) — list, viewport, textinput components 251 251 + - [Glamour](https://github.com/charmbracelet/glamour) — Markdown → terminal rendering 252 252 + - [Lipgloss](https://github.com/charmbracelet/lipgloss) — styling 253 253 + - [go-imap/v2](https://github.com/emersion/go-imap) — IMAP client (RFC 6851 MOVE) 254 254 + - [go-message](https://github.com/emersion/go-message) — MIME parsing 255 255 + - [goldmark](https://github.com/yuin/goldmark) — Markdown → HTML for sending 256 256 + - [BurntSushi/toml](https://github.com/BurntSushi/toml) — config parsing 257 257 + 258 258 + ## Changelog 259 259 + 260 260 + See [CHANGELOG.md](CHANGELOG.md) for what's new. 261 261 + 262 262 + ## Benchmark 263 263 + 264 264 + neomd's responsiveness depends entirely on your IMAP server. Every folder switch, email open, and move requires IMAP round-trips (SELECT + UID SEARCH + FETCH). Here are real measurements from the same machine, same network: 265 265 + 266 266 + **Hostpoint** (dedicated email provider) — folder switch: **~33ms total** 267 267 + | Operation | Time | 268 268 + |-----------|------| 269 269 + | SELECT | 12ms | 270 270 + | UID SEARCH | 10ms | 271 271 + | FETCH (200 emails) | 76ms | 272 272 + | MOVE (1 email) | 46ms | 273 273 + 274 274 + **Gmail** — folder switch: **~570ms total** (17x slower than Hostpoint) 275 275 + | Operation | Time | 276 276 + |-----------|------| 277 277 + | SELECT | 200ms | 278 278 + | UID SEARCH | 180ms | 279 279 + | FETCH (2 emails) | 190ms | 280 280 + | MOVE (1 email) | 339ms | 281 281 + 282 282 + **Outlook/Office365** (with OAuth2 authentication and different network - not really comparable, but gives a indication) — folder switch: **~269ms total** (8x slower than Hostpoint) 283 283 + | Operation | Time | 284 284 + |-----------|------| 285 285 + | SELECT | 45ms | 286 286 + | UID SEARCH | 22ms | 287 287 + | FETCH (10 emails) | 180ms | 288 288 + | MOVE (1 email) | 21ms | 289 289 + 290 290 + Interestingly, Gmail benchmarks fast on a **fresh single connection** (`scripts/imap-benchmark.sh` shows ~70ms total, same as Hostpoint). But on a **sustained session** with sequential commands — which is how neomd actually uses IMAP — Gmail adds ~180ms latency per command. This is likely Gmail's internal label-to-folder translation and session management overhead. The result: every action in neomd feels much slower on Gmail, while Hostpoint stays instant. 291 291 + 292 292 + 293 293 + {{< callout type="info" >}} 294 294 + **Gmail is not recommended.** If you're on Gmail, consider a dedicated email provider (Hostpoint, Fastmail, HEY, Migadu, etc.) for the best neomd experience. Or use Gmail just for fun :). See [docs/content/docs/configurations/gmail.md](docs/content/docs/configurations/gmail.md) for Gmail-specific folder configuration. 295 295 + {{< /callout >}} 296 296 + 297 297 + 298 298 + **Test your own provider:** 299 299 + ```bash 300 300 + # With password 301 301 + IMAP_HOST=imap.example.com IMAP_USER=me@example.com IMAP_PASS=secret ./scripts/imap-benchmark.sh 302 302 + 303 303 + # With OAuth2 (reads token from neomd config) 304 304 + CONFIG=~/.config/neomd/config.toml IMAP_USER=me@gmail.com ./scripts/imap-benchmark.sh 305 305 + ``` 306 306 + 307 307 + ## Security 308 308 + 309 309 + See [SECURITY.md](SECURITY.md) for how credentials, screener lists, temp files, and network connections are handled — with links to the relevant source files. 310 310 + 311 311 + ## Inspirations 312 312 + 313 313 + - [Neomutt](https://neomutt.org) — the gold standard terminal email client; neomd reuses its screener list format and borrows keybindings (though most are [custom made](https://github.com/sspaeti/dotfiles/blob/master/mutt/.config/mutt/muttrc) and what I use). I implemented the [HEY screener for Neomutt](https://www.ssp.sh/brain/hey-screener-in-neomutt), see note for more information. 314 314 + - [HEY](https://www.hey.com/features/the-screener/) — the Screener concept: unknown senders wait for a decision before reaching your inbox 315 315 + - [hey-cli](https://github.com/basecamp/hey-cli) — a Go CLI for HEY; provided the bubbletea patterns used here 316 316 + - [newsboat](https://newsboat.org) — RSS reader whose `O` open-in-browser binding and vim navigation feel inspired neomd's reader view 317 317 + - [emailmd.dev](https://www.emailmd.dev) — the idea that email should be written in Markdown when seen on [HN](https://news.ycombinator.com/item?id=47505144) 318 318 + - [charmbracelet/pop](https://github.com/charmbracelet/pop) — minimal Go email sender from Charm 319 319 + - [charmbracelet/glamour](https://github.com/charmbracelet/glamour) — Markdown rendering in the terminal 320 320 + - [kanagawa.nvim](https://github.com/rebelot/kanagawa.nvim) — the color palette used for the inbox 321 321 + - [msgvault](https://github.com/wesm/msgvault) — Go IMAP archiver; the IMAP client code in neomd is adapted from it 322 322 + 323 323 + ## Disclaimer 324 324 + 325 325 + This TUI is mostly [vibe-coded](https://www.ssp.sh/brain/vibe-coding) in the sense that all code is written with Claude Code, but guided by very detailed instructions to make the workflow as I use it and like it to be. 326 326 + 327 327 + I used my experience with Neomutt, TUIs, and the GTD workflow for handling emails with HEY Screener, and added some (hopefully) _taste_ using my favorite tools and aesthetics. Find the full history at [Twitter](https://xcancel.com/sspaeti/status/2036539855182627169#m) - inspired by seeing [Email.md](https://www.emailmd.dev/) on HackerNews. 328 328 + 329 329 + If you [rather read the prompt](https://www.ssp.sh/brain/id-rather-read-the-prompt), check out my [initial prompt](https://github.com/ssp-data/neomd/blob/main/docs/initial-prompt/prompt.md) and its generated [plan](https://github.com/ssp-data/neomd/blob/main/docs/initial-prompt/prompt-plan.md) - which I have iterated and added features by the 100s since then. 330 330 + ## Roadmap 331 331 + 332 332 + See at my second brain at [Roadmap](https://www.ssp.sh/brain/neomd#roadmap).

-331

docs/content/docs/overview.md

reviewed

··· 1 1 - --- 2 2 - title: Overview & Philosophy 3 3 - weight: -10 4 4 - --- 5 5 - 6 6 - A minimal terminal email client for people who write in Markdown and live in Neovim. 7 7 - 8 8 - [Neomd](https://www.ssp.sh/brain/neomd/) is my way of implementing an email TUI based on my experience with Neomutt, focusing on [Neovim](https://www.ssp.sh/brain/neovim) (input) and reading/writing in [Markdown](https://www.ssp.sh/brain/markdown) and navigating with [Vim Motions](https://www.ssp.sh/brain/vim-language-and-motions) with the GTD workflow and [HEY-Screener](https://www.hey.com/features/the-screener/). 9 9 - 10 10 - 11 11 - {{< callout type="warning" >}} 12 12 - neomd moves, deletes, and modifies emails directly on your IMAP server. These operations affect your mailbox across all devices. **Back up important emails before first use.** neomd is experimental software and can't take responsibility for lost or misplaced emails. Consider testing with a secondary email account first. 13 13 - {{< /callout >}} 14 14 - 15 15 - 16 16 - ## The philosophy behind Neomd: What's unique? 17 17 - 18 18 - The key here is **speed** in which you can **navigate, read, and process** your email. Everything is just a shortcut away, and instantly (ms not seconds). It's similar to the foundations that Superhuman was built on: it runs on Gmail and makes it fast with vim commands. 19 19 - 20 20 - With the **HEY-Screener**, you get only emails in your inbox that you _screened in_, no spam or sales pitch before you added them. Or don't like them, just screen them out, and they get automatically moved to the "ScreenedOut" folder. 21 21 - 22 22 - With the [GTD approach](https://www.ssp.sh/brain/getting-things-done-gtd), using folders such as next (inbox), waiting, someday, scheduled, or archive, you can move them with one shortcut. This allows you quickly to move emails you need to wait for, or deal with later, in the right category. **Processing your email only once**. 23 23 - 24 24 - With the additional **Feed** and **Papertrail**, two additional features from HEY, you can read newsletters (just hit F) on them automatically in their separate tab, or move all your receipts into the Papertrail. Once you mark them as feed or papertrail, they will moved there automatically going forward. So you decide whether to read emails or news by jumping to different tabs. 25 25 - 26 26 - 27 27 - {{< callout type="info" >}} 28 28 - neomd's **speed** depends entirely on your IMAP provider. On Hostpoint (the provider I use), a folder switch takes **~33ms** which feels instant. On Gmail, the same operation takes **~570ms** which is noticeably slow. See [Benchmark](#benchmark) for full details and how to test your provider. 29 29 - {{< /callout >}} 30 30 - 31 31 - 32 32 - ## Screenshots 33 33 - 34 34 - ### Overview: List-View 35 35 - 36 36 - Feed view with all Newsletters - also workflow with differnt tabs and unread counter only for certain tabs (not all): 37 37 -  38 38 - 39 39 - ### Reading Panel 40 40 - 41 41 - Reading an email with Markdown 💙: 42 42 - 43 43 -  44 44 - 45 45 - ### Sent emails 46 46 - This is the markdown sent: 47 47 - 48 48 - ```markdown 49 49 - # [neomd: to: email@domain.com] 50 50 - # [neomd: subject: this is an email from neomd!] 51 51 - 52 52 - This email is from Neomd. Great I can add links such as [this](https://ssp.sh) with plain Markdown. 53 53 - 54 54 - E.g. **bold** or _italic_. 55 55 - 56 56 - ## Does headers work too? 57 57 - 58 58 - this is a text before a h3. 59 59 - 60 60 - ### H3 header 61 61 - 62 62 - how does that look in an email? 63 63 - Best regards 64 64 - ``` 65 65 - 66 66 - *Compose emails in your editor, read them rendered with [glamour](https://github.com/charmbracelet/glamour), and manage your inbox with a [HEY-style screener](https://www.hey.com/features/the-screener/) — all from the terminal.* 67 67 - 68 68 - 69 69 - Which looks like this: 70 70 - 71 71 -  72 72 - 73 73 - Or in Gmail: 74 74 -  75 75 - 76 76 - 77 77 - ### Video 78 78 - 79 79 - YouTube rundown of most features: 80 80 - [](https://youtu.be/8aKkldYLWV8) 81 81 - *(shorter but limited showcase [part 1 video](https://youtu.be/lpmHqIrCC-w))* 82 82 - 83 83 - 84 84 - ## Features 85 85 - 86 86 - - **Write in Markdown, send beautifully** — compose in `$EDITOR` (defaults to `nvim`), send as `multipart/alternative`: raw Markdown as plain text + goldmark-rendered HTML so recipients get clickable links, bold, headers, inline code, and code blocks 87 87 - - **Pre-send review** — after closing the editor, review To/Subject/body before sending; attach files, save to Drafts, or re-open the editor — no accidental sends 88 88 - - **Attachments** — attach files from the pre-send screen via yazi (`a`); images appear inline in the email body, other files as attachments; also attach from within neovim via `<leader>a`; the reader lists all attachments (including inline images) and `1`–`9` downloads and opens them 89 89 - - **Link opener** — links in emails are numbered `[1]`-`[0]` in the reader header; press `space+digit` to open in `$BROWSER` 90 90 - - **CC, BCC, Reply-all** — optional Cc/Bcc fields (toggle with `ctrl+b`); `R` in the reader replies to sender + all CC recipients 91 91 - - **Drafts** — `d` in pre-send saves to Drafts (IMAP APPEND); `E` in the reader re-opens a draft as an editable compose; compose sessions are auto-backed up to `~/.cache/neomd/drafts/` so you never lose an unsent email (`:recover` to reopen) 92 92 - - **HTML signatures** — configure separate text and HTML signatures; text signature appears in editor and plain text part, HTML signature in HTML part only; use `[html-signature]` placeholder to control inclusion per-email 93 93 - - **Multiple From addresses** — define SMTP-only `[[senders]]` aliases (e.g. `s@ssp.sh` through an existing account); cycle with `ctrl+f` in compose and pre-send; sent copies always land in the Sent folder 94 94 - - **Undo** — `u` reverses the last move or delete (`x`, `A`, `M*`) using the UIDPLUS destination UID 95 95 - - **Search** — `/` filters loaded emails in-memory; `space /` or `:search` runs IMAP SEARCH across all folders (only fetching header capped at 100 per folder) with results in a temporary "Search" tab; supports `from:`, `subject:`, `to:` prefixes 96 96 - - **Address autocomplete** — To/Cc/Bcc fields autocomplete from screener lists; navigate with `ctrl+n`/`ctrl+p`, accept with `tab` 97 97 - - **Everything view** — `ge` or `:everything` shows the 50 most recent emails across all folders; find emails that were screened out, moved to spam, or otherwise hard to locate 98 98 - - **Threaded inbox** — related emails are grouped together in the inbox list with a vertical connector line (`│`/`╰`), Twitter-style; threads are detected via `In-Reply-To`/`Message-ID` headers with a subject+participant fallback; newest reply on top, root at bottom; `·` reply indicator shows which emails you've answered 99 99 - - **Conversation view** — `T` or `:thread` shows the full conversation across folders (Inbox, Sent, Archive, etc.) in a temporary tab with `[Folder]` prefix; see your replies alongside received emails 100 100 - - **Glamour reading** — incoming emails rendered as styled Markdown in the terminal 101 101 - - **HEY-style screener** — unknown senders land in `ToScreen`; press `I/O/F/P` to approve, block, mark as Feed, or mark as PaperTrail; reuses your existing `screened_in.txt` lists from neomutt 102 102 - - **Folder tabs** — Inbox, ToScreen, Feed, PaperTrail, Archive, Waiting, Someday, Scheduled, Sent, Trash, ScreenedOut 103 103 - - **Multi-select** — `m` marks emails, then batch-delete, move, or screen them all at once 104 104 - - **Auto-screen on load** — screener runs automatically every time the Inbox loads (startup, `R`); keeps your inbox clean without pressing `S` (configurable, on by default) 105 105 - - **Background sync** — while neomd is open, inbox is fetched and screened every 5 minutes in the background; interval configurable, set to `0` to disable 106 106 - - **Kanagawa theme** — colors from the [kanagawa.nvim](https://github.com/rebelot/kanagawa.nvim) palette 107 107 - - **IMAP + SMTP** — direct connection via RFC 6851 MOVE, no local sync daemon required and keeps it in sync if you use it on mobile or different device 108 108 - 109 109 - ## Install 110 110 - 111 111 - **Prerequisites:** [Go 1.22+](https://go.dev/doc/install) and `make`. 112 112 - 113 113 - {{< callout type="info" >}} 114 114 - **Optional attachment helpers:** 115 115 - - `yazi` enables the built-in file picker used by pre-send `a` 116 116 - - custom Neovim integration in `custom.lua` enables inline `<leader>a` attachment insertion inside `neomd-*.md` buffers 117 117 - - without these, neomd still works; the inline Neovim attachment workflow just won't be available 118 118 - {{< /callout >}} 119 119 - 120 120 - 121 121 - ```sh 122 122 - git clone https://github.com/ssp-data/neomd 123 123 - cd neomd 124 124 - make install # installs to ~/.local/bin/neomd 125 125 - ``` 126 126 - 127 127 - Or just build locally: 128 128 - 129 129 - ```sh 130 130 - make build 131 131 - ./neomd 132 132 - ``` 133 133 - 134 134 - Or if on Arch Linux (AUR), you can use my [neomd-bin](https://aur.archlinux.org/packages/neomd-bin) via: 135 135 - ```sh 136 136 - yay -S neomd-bin 137 137 - ``` 138 138 - 139 139 - 140 140 - On first run, neomd: 141 141 - 1. Creates `~/.config/neomd/config.toml` with placeholders — fill in your IMAP/SMTP credentials 142 142 - - Important: Make sure that the Capitalization and naming of folder in `config.toml` is accroding to webmail IMAP, e.g. [Gmails](configurations/gmail) uses `sent = "[Gmail]/Sent Mail"` and not `sent` etc. 143 143 - 2. Creates `~/.config/neomd/lists/` for screener allowlists (or uses your custom paths from config) 144 144 - 3. Creates any missing IMAP folders (ToScreen, Feed, PaperTrail, etc.) automatically 145 145 - 146 146 - 147 147 - Neomd also runs on Android (more for fun) — see [configurations/android](configurations/android). 148 148 - 149 149 - ## Configuration 150 150 - 151 151 - On first run, neomd creates `~/.config/neomd/config.toml` with placeholders: 152 152 - 153 153 - ```toml 154 154 - [[accounts]] 155 155 - name = "Personal" 156 156 - imap = "imap.example.com:993" # :993 = TLS, :143 = STARTTLS 157 157 - smtp = "smtp.example.com:587" 158 158 - user = "me@example.com" 159 159 - password = "app-password" 160 160 - from = "Me <me@example.com>" 161 161 - starttls = false 162 162 - tls_cert_file = "" # optional PEM cert/CA for self-signed local bridges 163 163 - 164 164 - # Root-level settings 165 165 - store_sent_drafts_in_sending_account = false # default: Sent/Drafts use first account; true = follow sending account 166 166 - 167 167 - [screener] 168 168 - screened_in = "~/.config/neomd/lists/screened_in.txt" 169 169 - screened_out = "~/.config/neomd/lists/screened_out.txt" 170 170 - feed = "~/.config/neomd/lists/feed.txt" 171 171 - papertrail = "~/.config/neomd/lists/papertrail.txt" 172 172 - spam = "~/.config/neomd/lists/spam.txt" 173 173 - ``` 174 174 - 175 175 - Use an app-specific password (Gmail, Fastmail, Hostpoint, etc.) rather than your main account password. The `password` and `user` fields support environment variable expansion (`$VAR` or `${VAR}`) so you can avoid storing secrets in the config file. 176 176 - 177 177 - For the full configuration reference including multiple accounts, OAuth2 authentication, `[[senders]]` aliases, folder customization, signatures, and UI options, see [configuration](configuration). 178 178 - 179 179 - **Provider-specific guides:** 180 180 - - Gmail: [configurations/gmail](configurations/gmail) — folder name mapping and OAuth2 setup 181 181 - - Proton Mail Bridge: [configurations/proton-bridge](configurations/proton-bridge) — non-standard port configuration 182 182 - 183 183 - ### Onboarding 184 184 - 185 185 - On first launch, **auto-screening is paused** because your screener lists are empty — neomd won't move anything until you've classified your first sender. Your Inbox loads normally so you can explore. 186 186 - 187 187 - By default, neomd loads and auto-screens only the newest `200` Inbox emails (`[ui].inbox_count`). This keeps startup predictable. If you want to re-screen the entire Inbox on the IMAP server, run `:screen-all` inside neomd; that scans every Inbox email, not just the loaded subset, and can take a while on large mailboxes. 188 188 - 189 189 - **Getting started with the screener:** 190 190 - 191 191 - 1. From your Inbox, pick an email and press `I` (screen **in**) to approve the sender, or `O` (screen **out**) to block them. This creates your first screener list entry. 192 192 - 2. Once you've classified at least one sender, auto-screening activates on every Inbox load — new emails from known senders are sorted automatically. 193 193 - 3. Unknown senders land in the `ToScreen` tab. Jump there with `gk` (or `Tab`, use `L` or click the tab) and classify them: 194 194 - - `I` screen **in** — sender stays in Inbox forever 195 195 - - `O` screen **out** — sender never reaches Inbox again 196 196 - - `F` **feed** — newsletters go to the Feed tab 197 197 - - `P` **papertrail** — receipts go to the PaperTrail tab 198 198 - 4. Use `m` to mark multiple emails, then `I` to batch-approve them all at once. From the `ToScreen` folder, approving/blocking a single unmarked message now applies to all currently queued mail from that sender. 199 199 - 200 200 - **The best part:** all classifications are saved permanently in your screener lists (`screened_in.txt`, `screened_out.txt`, etc.). An email address screened in will automatically go to your Inbox, and any email screened out will never be in your Inbox again. 201 201 - 202 202 - You choose who can land in your Inbox. Bye-bye spam. This is the beauty of [HEY-Screener](https://www.hey.com/features/the-screener/), and neomd implements the same concept. 203 203 - 204 204 - {{< callout type="info" >}} 205 205 - To disable auto-screening entirely, set `auto_screen_on_load = false` in `[ui]` config. Run `:debug` inside neomd if something isn't working. 206 206 - {{< /callout >}} 207 207 - 208 208 - 209 209 - {{< callout type="warning" >}} 210 210 - `:screen-all` operates on the full Inbox mailbox on the server, not just the emails currently loaded in the UI. Use it when you intentionally want a mailbox-wide reclassification pass. 211 211 - {{< /callout >}} 212 212 - 213 213 - 214 214 - ### Screener Workflow 215 215 - 216 216 - Find full Screener Workflow at [screener](screener), classification tables, and bulk re-classification instructions. 217 217 - ### Keybindings 218 218 - 219 219 - Press `?` inside neomd to open the interactive help overlay. Start typing to filter shortcuts. 220 220 - 221 221 - See the [full keybindings reference](keybindings) (auto-generated from [`internal/ui/keys.go`](internal/ui/keys.go) via `make docs`). 222 222 - 223 223 - ### How Sending Works 224 224 - 225 225 - Compose in Markdown, send as `multipart/alternative` (plain text + HTML). Attachments, CC/BCC, multiple From addresses, drafts, and pre-send review are all supported. 226 226 - 227 227 - Discarding unsent mail now asks for confirmation in compose/pre-send, and `:recover` reopens the latest backup if you want to resume after an abort. 228 228 - 229 229 - - See [sending](sending) for details on MIME structure, attachments, pre-send review, and drafts. 230 230 - - See [reading](reading) for the reader: images, inline links, attachments, and navigation. 231 231 - 232 232 - ### Dev: Makefile Commands 233 233 - 234 234 - ``` 235 235 - make build compile ./neomd 236 236 - make run build and run 237 237 - make install install to ~/.local/bin 238 238 - make test run tests 239 239 - make vet go vet 240 240 - make fmt gofmt -w . 241 241 - make tidy go mod tidy 242 242 - make clean remove compiled binary 243 243 - make help print this list 244 244 - ``` 245 245 - 246 246 - ## Stack 247 247 - 248 248 - - [Bubble Tea](https://github.com/charmbracelet/bubbletea) — TUI framework 249 249 - - [Bubbles](https://github.com/charmbracelet/bubbles) — list, viewport, textinput components 250 250 - - [Glamour](https://github.com/charmbracelet/glamour) — Markdown → terminal rendering 251 251 - - [Lipgloss](https://github.com/charmbracelet/lipgloss) — styling 252 252 - - [go-imap/v2](https://github.com/emersion/go-imap) — IMAP client (RFC 6851 MOVE) 253 253 - - [go-message](https://github.com/emersion/go-message) — MIME parsing 254 254 - - [goldmark](https://github.com/yuin/goldmark) — Markdown → HTML for sending 255 255 - - [BurntSushi/toml](https://github.com/BurntSushi/toml) — config parsing 256 256 - 257 257 - ## Changelog 258 258 - 259 259 - See [CHANGELOG.md](CHANGELOG.md) for what's new. 260 260 - 261 261 - ## Benchmark 262 262 - 263 263 - neomd's responsiveness depends entirely on your IMAP server. Every folder switch, email open, and move requires IMAP round-trips (SELECT + UID SEARCH + FETCH). Here are real measurements from the same machine, same network: 264 264 - 265 265 - **Hostpoint** (dedicated email provider) — folder switch: **~33ms total** 266 266 - | Operation | Time | 267 267 - |-----------|------| 268 268 - | SELECT | 12ms | 269 269 - | UID SEARCH | 10ms | 270 270 - | FETCH (200 emails) | 76ms | 271 271 - | MOVE (1 email) | 46ms | 272 272 - 273 273 - **Gmail** — folder switch: **~570ms total** (17x slower than Hostpoint) 274 274 - | Operation | Time | 275 275 - |-----------|------| 276 276 - | SELECT | 200ms | 277 277 - | UID SEARCH | 180ms | 278 278 - | FETCH (2 emails) | 190ms | 279 279 - | MOVE (1 email) | 339ms | 280 280 - 281 281 - **Outlook/Office365** (with OAuth2 authentication and different network - not really comparable, but gives a indication) — folder switch: **~269ms total** (8x slower than Hostpoint) 282 282 - | Operation | Time | 283 283 - |-----------|------| 284 284 - | SELECT | 45ms | 285 285 - | UID SEARCH | 22ms | 286 286 - | FETCH (10 emails) | 180ms | 287 287 - | MOVE (1 email) | 21ms | 288 288 - 289 289 - Interestingly, Gmail benchmarks fast on a **fresh single connection** (`scripts/imap-benchmark.sh` shows ~70ms total, same as Hostpoint). But on a **sustained session** with sequential commands — which is how neomd actually uses IMAP — Gmail adds ~180ms latency per command. This is likely Gmail's internal label-to-folder translation and session management overhead. The result: every action in neomd feels much slower on Gmail, while Hostpoint stays instant. 290 290 - 291 291 - 292 292 - {{< callout type="info" >}} 293 293 - **Gmail is not recommended.** If you're on Gmail, consider a dedicated email provider (Hostpoint, Fastmail, HEY, Migadu, etc.) for the best neomd experience. Or use Gmail just for fun :). See [configurations/gmail](configurations/gmail) for Gmail-specific folder configuration. 294 294 - {{< /callout >}} 295 295 - 296 296 - 297 297 - **Test your own provider:** 298 298 - ```bash 299 299 - # With password 300 300 - IMAP_HOST=imap.example.com IMAP_USER=me@example.com IMAP_PASS=secret ./scripts/imap-benchmark.sh 301 301 - 302 302 - # With OAuth2 (reads token from neomd config) 303 303 - CONFIG=~/.config/neomd/config.toml IMAP_USER=me@gmail.com ./scripts/imap-benchmark.sh 304 304 - ``` 305 305 - 306 306 - ## Security 307 307 - 308 308 - See [SECURITY.md](SECURITY.md) for how credentials, screener lists, temp files, and network connections are handled — with links to the relevant source files. 309 309 - 310 310 - ## Inspirations 311 311 - 312 312 - - [Neomutt](https://neomutt.org) — the gold standard terminal email client; neomd reuses its screener list format and borrows keybindings (though most are [custom made](https://github.com/sspaeti/dotfiles/blob/master/mutt/.config/mutt/muttrc) and what I use). I implemented the [HEY screener for Neomutt](https://www.ssp.sh/brain/hey-screener-in-neomutt), see note for more information. 313 313 - - [HEY](https://www.hey.com/features/the-screener/) — the Screener concept: unknown senders wait for a decision before reaching your inbox 314 314 - - [hey-cli](https://github.com/basecamp/hey-cli) — a Go CLI for HEY; provided the bubbletea patterns used here 315 315 - - [newsboat](https://newsboat.org) — RSS reader whose `O` open-in-browser binding and vim navigation feel inspired neomd's reader view 316 316 - - [emailmd.dev](https://www.emailmd.dev) — the idea that email should be written in Markdown when seen on [HN](https://news.ycombinator.com/item?id=47505144) 317 317 - - [charmbracelet/pop](https://github.com/charmbracelet/pop) — minimal Go email sender from Charm 318 318 - - [charmbracelet/glamour](https://github.com/charmbracelet/glamour) — Markdown rendering in the terminal 319 319 - - [kanagawa.nvim](https://github.com/rebelot/kanagawa.nvim) — the color palette used for the inbox 320 320 - - [msgvault](https://github.com/wesm/msgvault) — Go IMAP archiver; the IMAP client code in neomd is adapted from it 321 321 - 322 322 - ## Disclaimer 323 323 - 324 324 - This TUI is mostly [vibe-coded](https://www.ssp.sh/brain/vibe-coding) in the sense that all code is written with Claude Code, but guided by very detailed instructions to make the workflow as I use it and like it to be. 325 325 - 326 326 - I used my experience with Neomutt, TUIs, and the GTD workflow for handling emails with HEY Screener, and added some (hopefully) _taste_ using my favorite tools and aesthetics. Find the full history at [Twitter](https://xcancel.com/sspaeti/status/2036539855182627169#m) - inspired by seeing [Email.md](https://www.emailmd.dev/) on HackerNews. 327 327 - 328 328 - If you [rather read the prompt](https://www.ssp.sh/brain/id-rather-read-the-prompt), check out my [initial prompt](docs/initial-prompt/prompt.md) and its generated [plan](docs/initial-prompt/prompt-plan.md) - which I have iterated and added features by the 100s since then. 329 329 - ## Roadmap 330 330 - 331 331 - See at my second brain at [Roadmap](https://www.ssp.sh/brain/neomd#roadmap).

+2 -2

scripts/sync-readme-to-docs.sh

reviewed

··· 6 6 7 7 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" 8 8 README="$REPO_ROOT/README.md" 9 9 - DOCS_OVERVIEW="$REPO_ROOT/docs/content/docs/overview.md" 9 9 + DOCS_OVERVIEW="$REPO_ROOT/docs/content/docs/_index.md" 10 10 11 11 if [[ ! -f "$README" ]]; then 12 12 echo "Error: README.md not found at $README" ··· 71 71 -e 's|images/|/images/|g' \ 72 72 >> "$DOCS_OVERVIEW" 73 73 74 74 - echo "✅ Synced README.md → docs/content/docs/overview.md" 74 74 + echo "✅ Synced README.md → docs/content/docs/_index.md" 75 75 echo " Next: Run 'make docs-build' to regenerate the site"