Skip to main content
Your inbox is a full-time job you never applied for. Wolffish connects to your Gmail via Google’s OAuth, reads your unread emails, summarizes what matters, and can reply, archive, label, and draft on your behalf. No browser automation. No screen scraping. Direct API access to your mailbox. One prompt. Every morning. Inbox zero.

​
Video Walkthrough

​
What You Need

  • Wolffish installed and running
  • An LLM API key configured in Settings > Models. DeepSeek V4 Flash recommended — fast, cheap, and more than capable for email summarization. Any other provider works too.
  • A Google account — any free Gmail works. No Google Workspace subscription required.

​
Part 1: Create a Google Cloud Project

You need a free Google Cloud project to generate OAuth credentials. This is a one-time setup that takes about 5 minutes.
1

Create a Google Cloud project

Go to Google Cloud Console and create a new project. Name it anything — “Wolffish” works.You’ll see the project dashboard with your project name in the top bar when it’s ready.
2

Enable the Gmail API

Go to APIs & Services > Library in the left sidebar. Search for Gmail API and click Enable.While you’re here, enable these too so the full Google Workspace integration works:
  • Gmail API
  • Google Drive API
  • Google Calendar API
  • Google Sheets API
  • Google Docs API
  • Google Slides API
  • Tasks API
  • People API
Each enabled API appears in the Enabled APIs & services dashboard. You can always come back and enable more later.
3

Configure the OAuth consent screen

Go to OAuth consent screen in the left sidebar.
  • Set User type to External
  • Fill in the required fields — app name (anything), your email for support contact
  • Skip scopes — Wolffish requests what it needs at authorization time
  • Under Test users, add your own Gmail address
  • Click Save
You’ll see the consent screen summary with status Testing. Leave it in Testing — only test users (you) can authorize, which is exactly what you want for personal use.
4

Create OAuth credentials

Go to Credentials in the left sidebar.
  • Click Create Credentials > OAuth client ID
  • Choose application type: Desktop app
  • Name it anything — “Wolffish” works
  • Click Create
The new client appears in the OAuth 2.0 Client IDs list.
5

Download the JSON file

Click the download icon (arrow down) next to your new client to get the JSON file.A file starting with client_secret_ downloads. This is your OAuth credentials file — keep it safe. You’ll drop it into Wolffish next.
This entire setup is free. Google Cloud gives every account a generous free tier that covers personal API usage with plenty of headroom. You will not be charged.

​
Part 2: Connect Wolffish to Google

1

Install the Google integration

Open Wolffish. Go to Settings > Services > Google Workspace.Click Install. This downloads the gog CLI binary (~50 MB) that Wolffish uses under the hood for all Google API calls. A progress bar shows the download.
2

Upload your OAuth credentials

In the same settings panel, find the OAuth Credentials section.Drag and drop the client_secret_*.json file you downloaded from Google Cloud Console. Wolffish validates it and shows your project ID and client ID.
3

Authorize your Gmail account

In the Accounts section, type your Gmail address and click Authorize.Your default browser opens to Google’s consent screen. Sign in, review the permissions, and click Allow. The browser redirects back and Wolffish confirms the account is connected.Your OAuth tokens are stored securely in your OS keyring (macOS Keychain, Windows Credential Manager, or Linux Secret Service) — not in any config file.
You can authorize multiple Google accounts. Wolffish fans out across all of them when you ask something generic like “check my email” — no need to specify which account each time.

​
Part 3: The Prompt

That’s it for setup. Go back to the Wolffish chat and send this: 
Check all my email accounts for unread messages in the inbox.

RULES — READ CAREFULLY:
- Fetch EVERY single unread email, however many there are.
  No caps, no pagination limits, no early stops.
- You MUST call google_gmail_read for EACH email individually.
  Reading the subject line or metadata from google_gmail_search
  is NOT enough — you need the full body content of every email.
- Do NOT skip emails because you think you already know what
  they're about from the search results. Search results give
  you metadata only. You MUST read the actual content.
- If there are 43 unread emails, I expect to see 43
  google_gmail_read calls. If there are 200, I expect 200.
  No exceptions.
- Work in batches of 10-15 reads per response. After each
  batch, continue with the remaining emails in your next
  response. Do NOT produce any summary, briefing, or final
  output until EVERY email has been read via google_gmail_read.
- Do NOT mark any email as read. Do NOT archive, label, move,
  or modify anything.

COMPLETION CHECK:
Before producing your final briefing, count how many
google_gmail_read calls you made. If that number is less than
the total unread count from google_gmail_search, you are NOT
done — go back and read the ones you missed.

BRIEFING FORMAT (only after ALL emails are read):
1. Total unread count per account
2. For each email:
   - Who it's from and when
   - One-line summary of what they want or what it's about
   - Priority: urgent (needs action today), normal, or low
     (newsletter/promo/notification)
3. At the end, list any emails that need a reply with a
   suggested one-liner I can approve or edit

​
How It Works

  1. Wolffish loads the Google Workspace capability and calls google_accounts to discover your authorized accounts.
  2. For each account, it calls google_gmail_search with is:unread in:inbox — one call per account, in parallel — fetching every unread message.
  3. For each unread thread, it calls google_gmail_read to get the full email content.
  4. The LLM reads every email and produces the structured briefing — sender, summary, priority.
  5. It suggests reply drafts for anything that needs a response.
No browser. No screenshots. No mouse clicks. Direct API calls to Gmail’s backend.

​
Going Further

The prompt above is a starting point. Here are variations you can try: 
Check my unread emails. For any email that's clearly
expecting a reply (a question, a request, an invitation),
draft a reply using google_gmail_draft_create. Match my
tone from soul.md. Don't send anything — just save drafts
for me to review.

Check all my email accounts for unread messages from the
last 24 hours. Write a markdown digest to
files/email-digest-today.md with sections: Action Required,
FYI, and Newsletters. Include sender, subject, and a
one-sentence summary for each. Mark newsletters as read.

Search my email for the most recent thread from
sarah@example.com about the Q3 budget. Read the full
thread and summarize the current state — what was agreed,
what's still open, and what I need to do next.

Give me a morning briefing:
1. Unread emails — summarize by priority
2. Today's calendar — list all events with times
3. Overdue tasks — anything past due in Google Tasks

Present it as one unified briefing, grouped by section.

​
Automating with Heartbeat

Once you trust the output, schedule it to run every morning. Open Settings > Heartbeat to launch the built-in heartbeat editor — paste the block below and save. See the Heartbeat docs for all schedule formats. 
## Gmail Briefing | Weekday (07:30)

Check all my email accounts for unread messages in the inbox.

RULES — READ CAREFULLY:
- Fetch EVERY single unread email, however many there are.
  No caps, no pagination limits, no early stops.
- You MUST call google_gmail_read for EACH email individually.
  Reading the subject line or metadata from google_gmail_search
  is NOT enough — you need the full body content of every email.
- Do NOT skip emails because you think you already know what
  they're about from the search results. Search results give
  you metadata only. You MUST read the actual content.
- If there are 43 unread emails, I expect to see 43
  google_gmail_read calls. If there are 200, I expect 200.
  No exceptions.
- Work in batches of 10-15 reads per response. After each
  batch, continue with the remaining emails in your next
  response. Do NOT produce any summary, briefing, or final
  output until EVERY email has been read via google_gmail_read.
- Do NOT mark any email as read. Do NOT archive, label, move,
  or modify anything.

COMPLETION CHECK:
Before producing your final briefing, count how many
google_gmail_read calls you made. If that number is less than
the total unread count from google_gmail_search, you are NOT
done — go back and read the ones you missed.

BRIEFING FORMAT (only after ALL emails are read):
1. Total unread count per account
2. For each email:
   - Who it's from and when
   - One-line summary of what they want or what it's about
   - Priority: urgent (needs action today), normal, or low
     (newsletter/promo/notification)
3. At the end, list any emails that need a reply with a
   suggested one-liner I can approve or edit
Change Weekday (07:30) to match your schedule — Daily (08:00) for every day, Cron (0 7 * * 1-5) for weekdays only, or Weekly (Monday 07:00) for a weekly digest.

​
Limits

  • OAuth “Testing” status — Your consent screen stays in “Testing” mode, which limits authorization to the test users you added (yourself). This is fine for personal use. If you want others to use it, you’d need to publish the app through Google’s verification process.
  • Token refresh — Tokens refresh automatically. If you revoke access from your Google Account security settings, re-authorize in Wolffish Settings.
  • Rate limits — Google’s Gmail API has generous free quotas (250 quota units per user per second). Normal personal usage won’t come close.
  • No attachment content — Wolffish can see attachment metadata (name, type, size) but doesn’t download or read attachment contents by default. You can ask it to download specific attachments via Google Drive.