README
¶
Godwit
An open-source, AI-native email client you can extend.
Godwit is a desktop email client for macOS, Windows and Linux. It works with any IMAP/SMTP account and ships with an AI assistant, Wit, that reads, summarizes, translates and drafts mail with the model you choose. Everything AI in it, the built-in features included, runs through the same extension points open to you: drop in a SKILL.md and a button appears.
The name comes from the bar-tailed godwit, which holds the record for the longest non-stop bird flight.
Status: 0.0.x, early preview. Expect rough edges, and keep a copy of anything important on your mail server.
Features
- Mail: IMAP/SMTP accounts with sync, offline changes, conversations, full-text search, and HTML compose with reply, forward, CC/BCC and drafts. Setup is detected for Gmail, Outlook (sign in with Microsoft), iCloud, Yahoo, AOL, QQ Mail, 163/126 Mail, Tencent Exmail, Feishu and DingTalk Mail, and any other IMAP server.
- Wit: an agent that answers questions about your mail, reads attachments (PDF, Office, CSV) and drafts replies. It never sends without your approval.
- AI actions: summarize, translate, adjust tone and length, and quick replies, on a message, a selection or a draft.
- Your models: any OpenAI-compatible (Chat Completions or Responses) or Anthropic-compatible service, including local ones like Ollama and LM Studio. API keys stay in the system keychain.
- Extensions:
- Skills: a
SKILL.md(Agent Skills) in the data directory'sskills/folder becomes a Wit skill, or an action button withgodwit-action-*metadata. - Plugins: TypeScript plugins with declared permissions add hooks, actions, cards and Wit tools. Types are in
sdk/godwit.d.ts. Plugins can read mail and write drafts; none can send. - Native plugins: a shared library behind a small C ABI (
sdk/native/godwit_plugin.h), for what a sandbox cannot do. It runs with all of Godwit's rights, so Godwit shows the risk and asks you to allow that exact file; a changed file needs your permission again. - MCP servers: give Wit external tools. Each server is approved once, and each write call every time.
- Skills: a
- For other agents:
godwit mcpis an MCP server that lets Claude, Cursor and other agents read your mail and create drafts, but never send. Turn on Settings › Local API and copy the client configuration from there. - Updates itself from dl.godwit.email (the Microsoft Store version is updated by the Store).
Install
Download the latest build from godwit.email:
-
macOS: the
.dmg, or with Homebrew:brew install godwit-email/tap/godwit -
Windows: the installer, which installs for the current user without admin rights, or Godwit on the Microsoft Store, which the Store updates.
-
Linux: the
.deb, or install for the current user (no root) with:curl -fsSL https://dl.godwit.email/install.sh | sh
Command line
godwit [--data-dir DIR] the desktop app
godwit --headless [--data-dir DIR] serve the Local API without a window
godwit call [--data-dir DIR] METHOD [JSON_ARGS_ARRAY] call the running Godwit once
godwit mcp [--data-dir DIR] an MCP server on stdio for agents
godwit dev-sync-db replace the dev database from production (development builds only)
godwit --version
Development
Godwit is written in Go on MyGo: the main window is native UI, while compose, the Wit page and the message reader are React pages in web/. mise installs the pinned Go and Bun:
mise install
mise run generate # install web dependencies and generate Go/TypeScript code before Go tests
mise run dev # run the app, reloading on changes
mise run dev:sync-db # replace the dev database from production; stop both apps first
go test ./... # Go tests
mise run web:check
mise run build # package for this machine into dist/
Native and web UI translations share internal/i18n/en.json and zh-Hans.json, using ICU MessageFormat. Edit these catalogs, run mise run generate to update the Go and TypeScript accessors, and validate with go tool mygo i18n check. MyGo's generated Go/TypeScript accessors and client are ignored by Git; do not edit them directly. Development, packaging and mise run web:check / web:test generate them automatically; run mise run generate before using Go commands directly.
Development builds (mygo dev and go run) use a separate Godwit-dev data
directory beside production's Godwit directory (on Windows, ~/.godwit-dev
beside ~/.godwit). GUI, headless, call and mcp all use the matching default;
an explicit --data-dir still takes precedence. Release builds keep their existing
directory. MYGO_ENV=production selects production defaults for an unpackaged binary.
To start dev with production mail and settings, quit both instances and run
mise run dev:sync-db, then mise run dev. This overwrites the dev database.
It copies committed WAL data, validates and migrates only the copy, and leaves
the production database untouched. It refuses to run while either directory is
owned by a running instance. A database already upgraded by an older dev run is
not downgraded by this command.
The sync copies only the database. Dev gets a fresh keychain identity, so enter account credentials and model/plugin/MCP secrets again in dev. Cached attachments are downloaded again; draft attachments and outbox files are not copied, and their file references are cleared to avoid using production or stale dev files. Re-add draft attachments before sending from dev. Skills and plugin files are not copied. After you sign in, dev can sync and change the same remote mailbox.
Layout:
| Path | |
|---|---|
core/ |
the mail engine and service: sync, storage, send, AI, plugins, skills |
app/ |
the native UI |
web/, webui/ |
the web pages and their Go side |
cmd/godwit/ |
the executable: GUI, headless, call, mcp |
mcpserver/, rpc/ |
the MCP server and the Local API |
sdk/ |
plugin types |
docs/ |
design specs and plans |
site/ |
godwit.email, a Cloudflare Worker (mise run site:dev) |
The homepage's demo window and main download button share browser-platform detection. macOS shows traffic lights; Windows shows the app caption and right-hand window controls; Linux also uses right-hand controls. The window controls are decorative, not actions that close or resize the website.
Client CI always runs a lightweight changes check, but skips the desktop matrix and embedded-web checks when all changed paths are under site/. The separate Site workflow checks the website and deploys it from main. Shared configuration changes, such as mise.toml, and mixed site/client changes still run client CI.
Commit messages and PR titles follow Conventional Commits; release-please turns them into versions and the changelog. Merging its release PR builds every platform and uploads the installers and updates to the R2 bucket behind dl.godwit.email; each platform's update manifest goes up last, and installed apps update from it as soon as it is there.
Commits whose changed files are all under site/ are excluded from the application's version calculation and changelog by release-please's exclude-paths. Mixed changes, including a site change together with the root README.md, still participate in application releases.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
Package app is Godwit's desktop interface: one App whose view is rebuilt every frame from state that only the UI thread changes.
|
Package app is Godwit's desktop interface: one App whose view is rebuilt every frame from state that only the UI thread changes. |
|
Package assets embeds Godwit's brand assets.
|
Package assets embeds Godwit's brand assets. |
|
cmd
|
|
|
godwit
command
Command godwit is the Godwit desktop app, its headless server and the command-line client of its Local API (see run).
|
Command godwit is the Godwit desktop app, its headless server and the command-line client of its Local API (see run). |
|
godwit-registry
command
Command godwit-registry checks and signs a Godwit plugin registry.json (docs/registry/README.md).
|
Command godwit-registry checks and signs a Godwit plugin registry.json (docs/registry/README.md). |
|
Package contract checks that the Local API behaves like *core.Service: the same scenarios run against the typed service and through JSON-RPC.
|
Package contract checks that the Local API behaves like *core.Service: the same scenarios run against the typed service and through JSON-RPC. |
|
Package core is Godwit's mail engine.
|
Package core is Godwit's mail engine. |
|
ai
Package ai talks to model services.
|
Package ai talks to model services. |
|
auth
Package auth holds the provider table and account auto-detection.
|
Package auth holds the provider table and account auto-detection. |
|
conn
Package conn dials and authenticates IMAP and SMTP connections.
|
Package conn dials and authenticates IMAP and SMTP connections. |
|
coretest
Package coretest is a real core.Service for tests outside core: a mocked keychain, fake IMAP / SMTP servers per account, a fake model service, a fake MCP server and fixture plugins, all on this machine.
|
Package coretest is a real core.Service for tests outside core: a mocked keychain, fake IMAP / SMTP servers per account, a fake model service, a fake MCP server and fixture plugins, all on this machine. |
|
events
Package events is a lossy in-process event bus for UI notifications.
|
Package events is a lossy in-process event bus for UI notifications. |
|
gateway
Package gateway decides whether an AI tool call may run, needs approval, or is denied, and audits every decision.
|
Package gateway decides whether an AI tool call may run, needs approval, or is denied, and audits every decision. |
|
internal/testllm
Package testllm is a fake model service for tests: the model-list endpoint and a scripted, streaming chat endpoint for each protocol (openai, openai-responses, anthropic).
|
Package testllm is a fake model service for tests: the model-list endpoint and a scripted, streaming chat endpoint for each protocol (openai, openai-responses, anthropic). |
|
internal/testmail
Package testmail provides in-memory IMAP and SMTP servers for tests.
|
Package testmail provides in-memory IMAP and SMTP servers for tests. |
|
internal/testoauth
Package testoauth is a fake OAuth 2.0 authorization and token server for tests, with a stand-in for the user's browser.
|
Package testoauth is a fake OAuth 2.0 authorization and token server for tests, with a stand-in for the user's browser. |
|
mail
Package mail parses MIME messages and sanitizes HTML bodies.
|
Package mail parses MIME messages and sanitizes HTML bodies. |
|
mailsync
Package mailsync pulls folders and messages from IMAP into the store.
|
Package mailsync pulls folders and messages from IMAP into the store. |
|
plugins
Package plugins runs third-party TypeScript plugins (spec 5.3–5.5): manifest validation, the sandbox and the ctx API.
|
Package plugins runs third-party TypeScript plugins (spec 5.3–5.5): manifest validation, the sandbox and the ctx API. |
|
send
Package send submits messages over SMTP.
|
Package send submits messages over SMTP. |
|
skills
Package skills loads SKILL.md directories (Agent Skills standard).
|
Package skills loads SKILL.md directories (Agent Skills standard). |
|
store
Package store is Godwit's SQLite storage layer.
|
Package store is Godwit's SQLite storage layer. |
|
internal
|
|
|
avatar
Package avatar discovers ordinary sender avatars without asserting brand trust.
|
Package avatar discovers ordinary sender avatars without asserting brand trust. |
|
i18n
Package i18n shares MyGo's message catalogs with the native UI and pages.
|
Package i18n shares MyGo's message catalogs with the native UI and pages. |
|
icons
Package icons parses the Remix Icon icons Godwit uses (web.RemixIcons, embedded from the remixicon package, v4.8.0, the last Apache-2.0 release), the line style, and the fill style of those a selected rail button or sidebar row shows.
|
Package icons parses the Remix Icon icons Godwit uses (web.RemixIcons, embedded from the remixicon package, v4.8.0, the last Apache-2.0 release), the line style, and the fill style of those a selected rail button or sidebar row shows. |
|
imagecache
Package imagecache is the privacy proxy's store for remote mail images: a directory of files named by their URL's hash, shared by all messages, bounded in size and evicted least recently used first.
|
Package imagecache is the privacy proxy's store for remote mail images: a directory of files named by their URL's hash, shared by all messages, bounded in size and evicted least recently used first. |
|
imagefetch
Package imagefetch fetches and checks images: the reader's image proxy and prefetch download remote ones through a client of its own (public hosts only, no cookies, no Referer, a generic User-Agent), and a message's inline ones count against one Budget.
|
Package imagefetch fetches and checks images: the reader's image proxy and prefetch download remote ones through a client of its own (public hosts only, no cookies, no Referer, a generic User-Agent), and a message's inline ones count against one Budget. |
|
kit
Package kit is Godwit's component set: shadcn/ui Nova looks (neutral) built on mygo's *Base widgets.
|
Package kit is Godwit's component set: shadcn/ui Nova looks (neutral) built on mygo's *Base widgets. |
|
palette
Package palette holds the Tailwind CSS colors Godwit draws with, copied verbatim from tailwindcss v4.1.14 theme.css (oklch lightness as 0–1).
|
Package palette holds the Tailwind CSS colors Godwit draws with, copied verbatim from tailwindcss v4.1.14 theme.css (oklch lightness as 0–1). |
|
richtext
Package richtext is Godwit's rich text model: mail bodies, compose content and Markdown become a flat list of blocks that the native UI draws (spec 5.5), and compose content goes back to HTML.
|
Package richtext is Godwit's rich text model: mail bodies, compose content and Markdown become a flat list of blocks that the native UI draws (spec 5.5), and compose content goes back to HTML. |
|
syslang
Package syslang detects the system UI language as a BCP 47 tag.
|
Package syslang detects the system UI language as a BCP 47 tag. |
|
theme
Package theme turns Godwit's settings into semantic colors and sizes drawn from internal/palette, and installs them as the mygo theme.
|
Package theme turns Godwit's settings into semantic colors and sizes drawn from internal/palette, and installs them as the mygo theme. |
|
worddiff
Package worddiff compares compose documents word by word, formatting included: the unit is a word (a CJK character, a run of whitespace, a punctuation mark) with its style and link.
|
Package worddiff compares compose documents word by word, formatting included: the unit is a word (a CJK character, a run of whitespace, a punctuation mark) with its style and link. |
|
Package mcpserver is godwit mcp: an MCP server that lets an agent read the user's mail and write drafts through the running Godwit's Local API, as the mcp role.
|
Package mcpserver is godwit mcp: an MCP server that lets an agent read the user's mail and write drafts through the running Godwit's Local API, as the mcp role. |
|
Package ownerlock makes one process the owner of a data directory.
|
Package ownerlock makes one process the owner of a data directory. |
|
Package rpc is Godwit's line-delimited JSON-RPC 2.0 transport: a strict subset of the spec (positive integer IDs, positional params, no batches), reflective dispatch over a target's methods, and cancellable streams.
|
Package rpc is Godwit's line-delimited JSON-RPC 2.0 transport: a strict subset of the spec (positive integer IDs, positional params, no batches), reflective dispatch over a target's methods, and cancellable streams. |
|
Package rpcbind composes core with rpc: core's error codes, redaction and the methods exposed over the Local API.
|
Package rpcbind composes core with rpc: core's error codes, redaction and the methods exposed over the Local API. |
|
scripts
|
|
|
imgproto
command
Imgproto is a throwaway WebKit probe for the remote-image redesign (not shipped): does a sandboxed srcdoc iframe load images from a custom scheme under its CSP, does loading="lazy" work inside it, and does CSS background-image.
|
Imgproto is a throwaway WebKit probe for the remote-image redesign (not shipped): does a sandboxed srcdoc iframe load images from a custom scheme under its CSP, does loading="lazy" work inside it, and does CSS background-image. |
|
Package webui owns the web UI's Go side: compose windows, their bound service and the theme variables.
|
Package webui owns the web UI's Go side: compose windows, their bound service and the theme variables. |