{"id":50328408,"url":"https://github.com/gausejakub/vimail","last_synced_at":"2026-05-29T08:03:50.997Z","repository":{"id":341641923,"uuid":"1170936343","full_name":"gausejakub/vimail","owner":"gausejakub","description":"Terminal email client with Vim keybindings","archived":false,"fork":false,"pushed_at":"2026-03-16T20:04:39.000Z","size":329,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-16T20:43:01.432Z","etag":null,"topics":["bubbletea","cli","email","email-client","go","golang","imap","smtp","terminal","tui","vim"],"latest_commit_sha":null,"homepage":"https://vimail.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gausejakub.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-02T17:33:02.000Z","updated_at":"2026-03-16T19:54:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gausejakub/vimail","commit_stats":null,"previous_names":["gausejakub/vimail"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gausejakub/vimail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gausejakub%2Fvimail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gausejakub%2Fvimail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gausejakub%2Fvimail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gausejakub%2Fvimail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gausejakub","download_url":"https://codeload.github.com/gausejakub/vimail/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gausejakub%2Fvimail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33642319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bubbletea","cli","email","email-client","go","golang","imap","smtp","terminal","tui","vim"],"created_at":"2026-05-29T08:03:49.510Z","updated_at":"2026-05-29T08:03:50.980Z","avatar_url":"https://github.com/gausejakub.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vimail\n\nA terminal-based email client with Vim-style modal keybindings, written in Go.\n\nvimail brings the speed of Vim navigation to your inbox with a 3-pane layout, modal editing, and multiple color themes.\n\n## Features\n\n- **Vim-style modal editing** — Normal, Insert, Visual, and Command modes\n- **3-pane layout** — Mailbox sidebar, message list, and preview pane\n- **8 color themes** — vimail, tokyonight, catppuccin, kanagawa, gruvbox, nord, matrix, system\n- **Hot-swappable themes** — Switch with `:theme \u003cname\u003e` at any time\n- **AI compose assistant** — `:ai` in the editor to draft or rewrite emails using any CLI agent\n- **Compose with Vim** — Full Vim keybindings in the message body editor\n- **Global search** — Press `/` to search across all accounts and folders\n- **Multiple accounts** — Manage several email accounts in one view\n- **Export to ZIP** — Press `E` to export messages with text, HTML, metadata, and attachments\n- **Attachments** — View metadata in preview, save to disk with `S`\n- **Visual mode batch ops** — Select messages with `v`, then delete (`d`) or mark as read (`r`)\n- **HTML email rendering** — Clean text conversion via html2text, open raw HTML in browser with `o`\n- **JSON auto-format** — Pretty-prints JSON bodies in the preview pane\n- **Incremental sync** — Per-account IMAP sync with loading indicators\n- **Offline operation queue** — Deletes, sends, and mark-read ops are queued in SQLite and retried on reconnect\n- **Pure Go** — No CGO required, single static binary\n\n## Requirements\n\n- Go 1.24+\n- A terminal with truecolor support (`COLORTERM=truecolor`)\n\n## Install\n\n### Download binary\n\nGrab the latest release from [GitHub Releases](https://github.com/gausejakub/vimail/releases/latest) — no Go required.\n\n### From source\n\n```sh\ngit clone https://github.com/gausejakub/vimail.git\ncd vimail\ngo build -o vimail .\n```\n\nMove the binary somewhere on your `$PATH`:\n\n```sh\nmv vimail ~/.local/bin/\n```\n\n### Go install\n\n```sh\ngo install github.com/gausejakub/vimail@latest\n```\n\n## Usage\n\n```sh\nvimail\n```\n\nIf built locally without moving to `$PATH`:\n\n```sh\n./vimail\n```\n\nvimail launches in fullscreen (alt-screen) mode. Press `q` or `:quit` to exit.\n\n### Account Setup\n\n1. Add accounts to `~/.config/vimail/config.toml` (see examples below)\n2. Run `vimail setup` to store credentials in your OS keyring\n\n```sh\nvimail setup\n```\n\nThis walks through each configured account and securely stores your password in the OS keyring. If credentials already exist, it will ask before overwriting.\n\n## Configuration\n\nvimail reads its config from `~/.config/vimail/config.toml`. If the file doesn't exist, defaults are used.\n\n```toml\n[general]\npreview_pane = true\n\n[theme]\nname = \"tokyonight\"\n```\n\n### Adding a Gmail account\n\nGmail requires an **app password** (regular passwords don't work with IMAP):\n\n1. Enable 2-Factor Authentication at https://myaccount.google.com/security\n2. Generate an app password at https://myaccount.google.com/apppasswords\n3. Copy the 16-character code\n4. Add to config:\n\n```toml\n[[accounts]]\nname = \"Gmail\"\nemail = \"you@gmail.com\"\nimap_host = \"imap.gmail.com\"\nimap_port = 993\nsmtp_host = \"smtp.gmail.com\"\nsmtp_port = 587\nauth_method = \"app-password\"\ntls = \"tls\"\n```\n\n5. Run `vimail setup` and paste the 16-character app password when prompted\n\n### Adding other providers\n\nMost providers work with a regular password or app password:\n\n```toml\n[[accounts]]\nname = \"Personal\"\nemail = \"alice@example.com\"\nimap_host = \"imap.example.com\"\nimap_port = 993\nsmtp_host = \"smtp.example.com\"\nsmtp_port = 587\nauth_method = \"plain\"       # \"plain\" | \"app-password\"\ntls = \"tls\"                 # \"tls\" (default) | \"starttls\" | \"none\"\n```\n\nCommon provider settings:\n\n| Provider | IMAP Host | IMAP Port | SMTP Host | SMTP Port |\n|----------|-----------|-----------|-----------|-----------|\n| Gmail | imap.gmail.com | 993 | smtp.gmail.com | 587 |\n| Outlook/Hotmail | outlook.office365.com | 993 | smtp.office365.com | 587 |\n| Yahoo | imap.mail.yahoo.com | 993 | smtp.mail.yahoo.com | 587 |\n| iCloud | imap.mail.me.com | 993 | smtp.mail.me.com | 587 |\n| Seznam.cz | imap.seznam.cz | 993 | smtp.seznam.cz | 465 |\n\nAfter adding accounts, run `vimail setup` to store credentials.\n\n## Keybindings\n\n### Navigation\n\n| Key | Action |\n|-----|--------|\n| `j` / `k` | Move down / up in current pane |\n| `10j` / `5k` | Move N lines down / up |\n| `h` / `l` | Switch pane left / right |\n| `gg` / `G` | Jump to top / bottom |\n| `500gg` / `500G` | Jump to line N |\n| `Ctrl+D` / `Ctrl+U` | Half-page scroll (preview) |\n| `Tab` / `Shift+Tab` | Next / previous pane |\n\n### Actions\n\n| Key | Action |\n|-----|--------|\n| `c` | Compose new message |\n| `r` | Reply to selected message |\n| `f` | Forward |\n| `dd` | Delete message |\n| `S` | Save attachments to ~/Downloads |\n| `E` | Export message(s) to ZIP |\n| `o` | Open in browser |\n| `R` | Refresh |\n| `Enter` | Open draft (in Drafts folder) |\n| `Ctrl+S` | Send message (in compose) |\n| `Esc` | Close overlay / save draft / clear search |\n| `/` | Search all accounts and folders |\n\n### Modes\n\n| Key | Action |\n|-----|--------|\n| `:` | Enter command mode |\n| `v` / `V` | Enter visual mode (select range, `d` to delete, `r` to mark read) |\n| `?` | Toggle help overlay |\n| `q` | Quit |\n\n### Commands\n\n| Command | Action |\n|---------|--------|\n| `:quit` / `:q` | Quit vimail |\n| `:theme \u003cname\u003e` | Switch theme |\n| `:sync` | Sync mail |\n| `:ai` | AI-assisted compose (default agent) |\n| `:ai \u003cname\u003e` | AI-assisted compose with a specific agent |\n| `:ops` / `:queue` | Show operation queue log |\n| `:ps` / `:processes` | Show running background processes |\n| `:search \u003cquery\u003e` / `:s \u003cquery\u003e` | Search messages across all accounts |\n\n### Available themes\n\n`vimail` `tokyonight` `catppuccin` `kanagawa` `gruvbox` `nord` `matrix` `system`\n\n## AI Compose Assistant\n\nvimail can use any CLI-based AI tool to help draft, rewrite, or reply to emails. Type `:ai` in the compose editor and the current body is sent to the AI agent — the response replaces the editor content.\n\n### How it works\n\n1. Open compose (`c`), reply (`r`), or a draft (`Enter`)\n2. Type a prompt in the body (e.g. \"write a polite decline to this meeting\")\n3. Press `Esc` to enter normal mode\n4. Type `:ai` and press `Enter`\n5. The hint line shows \"Thinking...\" while the agent runs\n6. The response replaces the editor body — review, edit, and send with `Ctrl+S`\n\nWhen replying, the quoted text (lines starting with `\u003e`) is included as context, so the agent writes a reply to the original message.\n\n### Default setup\n\nOut of the box, vimail uses [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-cli). If `claude` is in your `$PATH`, no configuration is needed — just use `:ai`.\n\n### Configuring agents\n\nAdd an `[ai]` section to `~/.config/vimail/config.toml` to define one or more agents:\n\n```toml\n[ai]\ndefault = \"claude\"\n\n[[ai.agents]]\nname = \"claude\"\ncmd = \"claude\"\nargs = [\"--print\", \"-p\", \"{prompt}\"]\n\n[[ai.agents]]\nname = \"ollama\"\ncmd = \"ollama\"\nargs = [\"run\", \"llama3.2\", \"{prompt}\"]\n\n[[ai.agents]]\nname = \"gemini\"\ncmd = \"gemini\"\nargs = [\"-p\", \"{prompt}\"]\n\n[[ai.agents]]\nname = \"gpt\"\ncmd = \"sgpt\"\nargs = [\"--no-md\", \"{prompt}\"]\n\n[[ai.agents]]\nname = \"local\"\ncmd = \"llm\"\nargs = [\"-m\", \"mistral\", \"{prompt}\"]\n```\n\nEach agent needs:\n\n| Field | Description |\n|-------|-------------|\n| `name` | Identifier used with `:ai \u003cname\u003e` |\n| `cmd` | Binary name or path (must be in `$PATH`) |\n| `args` | Arguments passed to the binary. `{prompt}` is replaced with the full prompt |\n\nThe `{prompt}` placeholder is replaced with the system prompt (which includes To, Subject, and compose context) plus the editor body.\n\n### Usage examples\n\n| Command | What happens |\n|---------|-------------|\n| `:ai` | Uses the default agent |\n| `:ai ollama` | Uses the agent named \"ollama\" |\n| `:ai gpt` | Uses the agent named \"gpt\" |\n\n### Compatible CLI tools\n\nAny tool that accepts a prompt as an argument and prints the response to stdout will work:\n\n- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-cli) — `claude --print -p`\n- [Ollama](https://ollama.com) — `ollama run \u003cmodel\u003e`\n- [llm](https://github.com/simonw/llm) — `llm -m \u003cmodel\u003e`\n- [Gemini CLI](https://github.com/google-gemini/gemini-cli) — `gemini -p`\n- [sgpt](https://github.com/tbckr/sgpt) — `sgpt --no-md`\n- [aichat](https://github.com/sigoden/aichat) — `aichat -m \u003cmodel\u003e`\n- [mods](https://github.com/charmbracelet/mods) — `mods`\n\n## Logs\n\nvimail writes structured JSON logs to `~/.local/share/vimail/vimail.log`. Every background operation (sync, fetch, send, delete, mark-read), user action, and error is logged with full context (account, folder, UID, duration).\n\nLogs auto-rotate at 10 MB and are deleted after 3 days.\n\n```sh\n# Tail logs in real time\ntail -f ~/.local/share/vimail/vimail.log | jq .\n\n# Filter errors\ncat ~/.local/share/vimail/vimail.log | jq 'select(.level == \"error\")'\n\n# Show sync operations for a specific account\ncat ~/.local/share/vimail/vimail.log | jq 'select(.op == \"sync\" and .account == \"you@gmail.com\")'\n```\n\n## Project structure\n\n```\nmain.go                          Entry point, subcommands (setup, help)\ninternal/\n  config/                        TOML config loading\n  auth/                          OS keyring, OAuth2 device flow, setup CLI\n  email/                         Domain types (Account, Folder, Message), Store interface\n  ai/                            AI agent CLI wrapper (claude, ollama, etc.)\n  logging/                       Async structured JSON logger with rotation\n  cache/                         SQLite schema + Store implementation\n  worker/                        IMAP worker, SMTP worker, Coordinator\n  mock/                          Mock data for dev mode\n  theme/                         Theme engine + 8 themes\n  tui/\n    app.go                       Root bubbletea model\n    keys/                        Mode enum + keybinding maps\n    util/                        Shared cross-component message types\n    layout/                      Container, split pane, overlay\n    components/\n      mailbox/                   Account \u0026 folder sidebar\n      msglist/                   Message list with viewport + visual mode\n      preview/                   Message preview with scroll + browser open\n      compose/                   Compose overlay with Vim editor\n      help/                      Help overlay\n      status/                    Status bar (mode badge, info)\npkg/\n  vimtea/                        Vim-style editor widget\n```\n\n## Running tests\n\n```sh\ngo test ./...\n```\n\n## Status\n\nvimail is functional with real IMAP/SMTP connectivity, app-password auth, SQLite message caching, incremental sync, and an offline operation queue. Falls back to mock data when no accounts are configured.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgausejakub%2Fvimail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgausejakub%2Fvimail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgausejakub%2Fvimail/lists"}