How to Use Godwit: The Beginner's Guide (Open-Source AI Email Client, the Wit Assistant, and the SKILL.md Extension Arc)

CodexFuse Team · 2026-11-03T09:24:33.734Z · 11 min read min read

Learn how to use Godwit, the free open-source AI email client: install it, connect any IMAP account, let Wit summarize and draft with your chosen model, extend with SKILL.md skills, and connect Claude via MCP.

How to Use Godwit: The Beginner's Guide (Open-Source AI Email Client, the Wit Assistant, and the SKILL.md Extension Arc)

This godwit tutorial shows you how to use Godwit, the Godwit email client for people who want an inbox they can make their own. It is a free and open-source AI-native email client for macOS, Windows, and Linux. First, a quick disambiguation: Godwit is named after the bar-tailed godwit, the migratory bird famous for its record non-stop flights — and it is not the same thing as an unrelated open-source CSV-migration tool that happens to share the name. This guide is about the email client.

Godwit connects to any IMAP/SMTP account and pairs it with an AI assistant called Wit, which reads, summarizes, translates, and drafts your mail with whatever model you choose — including local models. If you have ever wanted an inbox you can extend like a developer tool, this guide walks you through the install, your first account, your first Wit task, your first custom SKILL.md skill, and the godwit mcp branch that lets Claude or Cursor read your mail. One note before you start: the makers still label Godwit an early preview, with the warning to "expect some rough edges" — so keep your mail on the server while you learn. If you have never connected a desktop client to a custom mail account before, this business email setup guide covers the IMAP and SMTP basics you will need.

What Is Godwit, Exactly?

Godwit is an open-source, AI-native desktop email client for macOS, Windows, and Linux that connects to any IMAP/SMTP account and includes an AI assistant named Wit that reads, summarizes, translates, and drafts email using the AI model you choose — including local models — while never sending an email without your approval.

The product launched on Product Hunt on October 30, 2026, and the listing updated on November 2, 2026 shows a price of 0 USD — free and open source under Apache 2.0. The makers' pitch is blunt: "I built Godwit for people who want an email client they can make their own, including the AI models and tools they use." The project's GitHub repository was created on October 8, 2026, and at the time of writing the official site advertises version 1.25.0, released November 2, 2026, while the README still carries the 0.0.x early-preview status — so expect fast-moving software and check the release page before you install.

Install Godwit on Your Computer

Your first-run arc in six steps looks like this: install the desktop build, add your first account, pick Wit's AI model, run your first Wit task, drop in your first SKILL.md skill, and connect Claude through godwit mcp. Start with step one — installing takes minutes.

Godwit is self-updating after install, so you download it once and the app keeps itself current from the maker's download server. There is no Godwit account to create, no telemetry, and no server relaying your mail — your messages and search index live in the local data directory on your machine.

Add Your First Email Account

Open Godwit and add your first account the way any modern client does: enter your address, and Godwit auto-detects the server settings for the providers it knows. Auto-setup is detected for Gmail, Outlook ("sign in with Microsoft"), iCloud, Yahoo, AOL, QQ Mail, 163/126 Mail, Tencent Exmail, Lark/Feishu, and DingTalk Mail — or you can enter any IMAP server manually for a custom domain or business mailbox.

Your passwords and API keys never sit in config files: they are stored in your operating system's keychain. Once connected, Godwit syncs your mail with full-text search, conversations, and offline changes — so the inbox works even when your connection does not. Reply, forward, CC/BCC, and drafts all come from a proper HTML compose window, not a stripped-down web view.

Choose the AI Model Wit Will Use

Wit, the Godwit Wit AI assistant, answers questions about your mail, reads PDF, Office, and CSV attachments, and drafts replies for you. Before it can do any of that, you point it at a model: Godwit works with any OpenAI-compatible service (Chat Completions or Responses) or Anthropic-compatible service, including local models running on Ollama or LM Studio — so your mail can stay entirely on your machine if you prefer.

Point beginners at the model they already know how to run: this Ollama beginner guide shows how to get a local model running in minutes, which then becomes Wit's offline brain. If you would rather use a cloud model, paste your API key into Godwit's model settings and it lands in the system keychain. On macOS 26 and later, Wit can even translate messages with the system's built-in translation, free, with no model configured at all.

Your First Wit Task: Summarize a Thread

The fastest way to learn Wit is to make it do the chore every inbox owner dreads: reading a long thread. Here is the arc:

1. Open a conversation with several replies — the longer and messier, the better.
2. Select the messages (or the whole thread) and trigger the summarize AI action.
3. Read Wit's summary, then ask a follow-up question in plain words — "what did they actually agree on?" — to see Wit reason over the thread.
4. Ask Wit to draft a reply, adjust the tone or length with the built-in actions, and review the draft yourself.
5. Send the draft yourself, from Godwit, with your own click.

Wit's other built-in AI actions cover translate, adjust tone/length, and quick replies on a message, a selection, or a draft. The pattern is always the same: Wit proposes, you approve. Wit never sends an email without your approval — that approval gate is the article's safety spine, and it holds across every extension point below.

What Can Send Mail and What Cannot: The Safety Spine

Godwit is built for people who let AI loose inside their inbox, so the permission model deserves a table of its own. Read it before you install anything extra.

Two rules to remember: a plugin "can read mail and write drafts — none can send," in the README's own words. And MCP servers you connect to Wit follow the same caution: each server is approved once, and each write call is approved every time.

Add Your First Skill: The SKILL.md Extension Arc

Here is where Godwit stops being just another mail client. The built-in AI actions use the same extension points that are open to you: drop a SKILL.md file (an Agent Skill) into the skills/ folder of Godwit's data directory, and Wit gains a skill — or, with godwit-action-* metadata in the file, a button appears in the UI.

Think of a skill as a recipe card for Wit: you write the instructions once, and Wit follows them whenever the skill applies. A "summarize invoices into a table" SKILL.md, for example, would teach Wit to pull sender, amount, and due date from any attachment it opens. No rebuild, no restart — the file is the feature. That is the whole SKILL.md extension arc: write the file, the button appears, Wit can now do the thing.

For deeper integrations, Godwit offers TypeScript plugins with declared permissions (types ship at sdk/godwit.d.ts on npm as @godwit/sdk) that can add hooks, actions, cards, and Wit tools — plus native plugins through a C ABI for anything performance-critical. Native plugins run with all of Godwit's rights, which is why you must approve the exact plugin file yourself and re-approve it after any change.

Let Claude Read Your Mail: The godwit mcp Branch

The last extension arc is the one aimed at developers: godwit mcp runs Godwit as an MCP server on stdio, so Claude, Cursor, and other agents can read your mail and create drafts. Never send — the MCP surface reads and drafts only.

Enable it in Settings, under Intelligence and then AI apps, which hands you the client configuration to paste into your agent's MCP setup. (The README notes the settings path can move between preview versions, so check the current settings screen if it is not there.) If you have never set up a coding agent's tooling before, this Claude Code beginner guide covers the agent side of the setup. The CLI also exposes godwit --headless (the local API without a window) and godwit call METHOD for scripting Godwit from the terminal.

Godwit vs Thunderbird vs Superhuman

Godwit vs Thunderbird is the comparison most open-source users will reach for first. Thunderbird owns the classic open-source-client lane: folders, filters, encryption, and extensions built over two decades — read the Thunderbird beginner guide if that lane is home. Godwit is the AI-native lane: a newer codebase (Go on MyGo) with an AI assistant, local-model support, and an MCP server as first-class features, in exchange for early-preview rough edges.

Godwit vs Superhuman is the comparison for the AI-email crowd. Superhuman is the proprietary AI-email lane: a paid SaaS product with an onboarding call, keyboard-first workflow, and the famous split inbox — covered in this Superhuman beginner guide. Godwit is the open-source counterpoint: free, no account, no telemetry, AI you can point at your own models, and extensibility through SKILL.md and plugins instead of a vendor roadmap.

Godwit Pricing

Godwit pricing is the shortest section in this guide: it is free. The Product Hunt listing shows 0 USD, the product is open source under Apache 2.0, and the vendor pages describe no paid tiers, no per-seat fees, and no message caps — the README's install instructions contain no license key step. If you bring your own cloud model for Wit, you pay your model provider directly; the client itself costs nothing.

Five Beginner Mistakes to Avoid

Sources

• Godwit on Product Hunt (producthunt.com/products/godwit) — "I built Godwit for people who want an email client they can make their own"; IMAP/SMTP on macOS/Windows/Linux; Wit reads, summarizes, translates and drafts with the model you choose; free and open source, Apache 2.0, early preview; published 2026-10-30, updated 2026-11-02.
• Godwit GitHub README (github.com/godwit-email/godwit) — install methods per platform; SKILL.md skills and TypeScript/C ABI plugins; "can read mail and write drafts — none can send"; godwit mcp; 0.0.x early preview warning: "keep a copy of anything important on your mail server"; repo created 2026-10-08.
• Godwit official site (godwit.email) — latest version 1.25.0, released November 2, 2026; no account, no telemetry, no server relaying mail; passwords only in the system keychain.
• GetToolRank new releases (gettoolrank.com/new-releases/) — independent launch feed listing Godwit as "Free (open source) Apache-2.0".

Frequently Asked Questions

Is Godwit free?

Yes. Godwit is free and open source under Apache 2.0 — the Product Hunt listing shows a price of 0 USD, and the vendor pages describe no paid tiers or per-seat fees. You only pay your model provider if you point Wit at a cloud model instead of a local one.

Will Wit ever send an email without my permission?

No. Wit never sends an email without your approval. TypeScript plugins cannot send mail at all, and the godwit mcp server only lets agents read mail and create drafts — sending stays a human click.

Can I use Godwit with Gmail or Outlook?

Yes. Godwit auto-detects settings for Gmail, Outlook, iCloud, Yahoo, AOL, QQ Mail, 163/126 Mail, Tencent Exmail, Lark/Feishu, and DingTalk Mail — and any other account works over plain IMAP/SMTP.

Can Wit run on a local model so my mail never leaves my computer?

Yes. Wit supports any OpenAI- or Anthropic-compatible service, including local models via Ollama or LM Studio, and API keys stay in your system keychain. Since Godwit has no account, no telemetry, and no server relaying mail, a local model keeps everything on your machine.

Is Godwit stable enough for daily use?

Not yet as your only copy — that is the makers' own position: Godwit is an early preview with "rough edges," and the README says to keep a copy of anything important on your mail server. Try it on a secondary account first, leave mail on the server, and revisit once the version numbers climb past 1.25.0.