A minimal email TUI where you read with Markdown and write in Neovim.
neomd.ssp.sh/docs
email
markdown
neovim
tui
update claude
+21
-4
+21
-4
CLAUDE.md
+21
-4
CLAUDE.md
···
6
6
7
7
- `make build` — compile to `./neomd` (also regenerates `docs/keybindings.md` from `internal/ui/keys.go`)
8
8
- `make run ARGS="..."` — build and run
9
-
- `make install` — install to `~/.local/bin/neomd`
10
-
- `make test` — `go test ./...`
9
+
- `make install` — install to `~/.local/bin/neomd` (default target)
10
+
- `make test` — `go test ./...` (unit tests, no network)
11
+
- `make test-integration` — integration tests against real IMAP/SMTP (requires demo account env vars)
11
12
- `make vet` / `make fmt` / `make tidy`
12
-
- `make docs` — regenerate keybindings doc from `internal/ui/keys.go` (runs as part of `build`)
13
+
- `make docs` — regenerate keybindings doc from `internal/ui/keys.go` (runs as part of `build`) and sync README to docs site
14
+
- `make docs-serve` — serve Hugo docs locally at http://localhost:1313
15
+
- `make docs-build` — build Hugo docs site to `docs/public/`
13
16
- `make send-test TO=addr` — run `./cmd/sendtest` to send a test email
14
17
- `make demo` / `make demo-hp` — run with demo configs at `~/.config/neomd-demo/` and `~/.config/neomd-demo-hostpoint/`
15
18
- `make benchmark` — IMAP latency benchmark (requires `IMAP_PASS_SIMU`, `IMAP_APPPASS_GMAIL_NEOMD` env vars)
16
19
- `make android` — cross-compile ARM64 for Termux
20
+
- `make release VERSION=v0.1.0` — tag and push a new release (runs docs build, GitHub Actions handles publishing)
17
21
- Single test: `go test ./internal/smtp -run TestBuildMessage`
18
22
19
23
Requires Go 1.22+. Binary version is injected via `-ldflags -X main.version=$(git describe)`.
···
51
55
52
56
**Screener** (`internal/screener/`) reads line-based lists of email addresses from paths defined in config. Default paths are under `~/.config/neomd/lists/`. Classification (`I`/`O`/`F`/`P`) appends to the corresponding list file and moves the message to the matching folder. Auto-screening runs on Inbox load and on a 5-minute background timer (`ui.background_sync_interval`).
53
57
54
-
**Config** (`internal/config/`) — TOML at `~/.config/neomd/config.toml`, auto-created with placeholders. Supports multiple `[[accounts]]` and SMTP-only `[[senders]]` aliases (cycled with `ctrl+f` in compose/pre-send). `-config PATH` flag overrides location.
58
+
**Config** (`internal/config/`) — TOML at `~/.config/neomd/config.toml`, auto-created with placeholders. Supports multiple `[[accounts]]` and SMTP-only `[[senders]]` aliases (cycled with `ctrl+f` in compose/pre-send). OAuth2 authentication supported via `oauth2_client_id`, `oauth2_client_secret`, `oauth2_issuer_url`, `oauth2_scopes` fields. `-config PATH` flag overrides location.
59
+
60
+
**Documentation** — Hugo site in `docs/` served at https://ssp-data.github.io/neomd/. README.md is synced to `docs/content/overview.md` via `scripts/sync-readme-to-docs.sh`. Keybindings are auto-generated from `internal/ui/keys.go` via `cmd/docs/main.go` — never hand-edit the markdown tables.
61
+
62
+
**Package structure:**
63
+
- `internal/ui/` — bubbletea TUI: model.go (state machine), inbox.go, reader.go, compose.go, keys.go (single source of truth for keybindings)
64
+
- `internal/imap/` — IMAP client wrapper using go-imap/v2
65
+
- `internal/smtp/` — email sender, MIME builder (`BuildMessage` is the main entry point)
66
+
- `internal/screener/` — HEY-style sender classification
67
+
- `internal/config/` — TOML config parsing
68
+
- `internal/editor/` — spawns $EDITOR with neomd-*.md temp files
69
+
- `internal/render/` — glamour-based Markdown rendering for terminal
70
+
- `internal/mailtls/` — TLS/STARTTLS connection helpers
71
+
- `internal/oauth2/` — OAuth2 flow for Gmail/Office365
55
72
56
73
## Project-Specific Conventions
57
74