| name | superhuman |
| description | This skill should be used when the user asks to "check email", "read inbox", "send email", "reply to email", "search emails", "archive email", "snooze email", "star email", "add label", "forward email", "download attachment", "switch email account", "use snippet", "search contacts", "ask ai about email", "find email about", "what did someone say about", or needs to interact with Superhuman email client. For calendar, events, and scheduling use the morgen skill instead. |
| allowed-tools | Bash(superhuman:*) |
Superhuman Email & Calendar Automation
CLI and MCP server to control Superhuman email client via Chrome DevTools Protocol (CDP).
Requirements
- Bun runtime
- Superhuman.app running with remote debugging enabled
Setup
bun install
/Applications/Superhuman.app/Contents/MacOS/Superhuman --remote-debugging-port=9400
Container / Remote CDP
When running inside a Docker container or connecting to a remote host, set CDP_HOST:
export CDP_HOST=host.docker.internal
superhuman account auth
After initial account auth, most operations use cached tokens and don't need CDP. Tokens are stored at ~/.config/superhuman-cli/tokens.json and auto-refresh via OAuth.
CLI Usage
superhuman status
superhuman account auth
superhuman account list
superhuman account switch 2
superhuman account switch user@example.com
Reading Email
superhuman inbox
superhuman inbox --limit 20 --json
superhuman search "from:john subject:meeting"
superhuman search "project update" --limit 20
superhuman search "from:anthropic" --include-done
superhuman read <thread-id> --account user@gmail.com
superhuman read <thread-id> --account user@gmail.com --context 3
superhuman read <thread-id> --account user@gmail.com --json
Ask AI
Use Superhuman's AI to search emails, answer questions, or ask about specific threads:
superhuman ai "find emails about the Stanford cover letter"
superhuman ai "what did John say about the deadline?"
superhuman ai "Write an email inviting the team to a planning meeting"
superhuman ai <thread-id> "summarize this thread"
superhuman ai <thread-id> "what are the action items?"
superhuman ai <thread-id> "draft a professional reply"
The AI automatically determines whether to search, compose, or answer based on your prompt.
Contacts
superhuman contact search "john"
superhuman contact search "john" --limit 5 --json
superhuman contact search "john" --account user@gmail.com
Multi-Account Support
The --account flag allows operations on any linked account without switching the Superhuman UI:
superhuman contact search "john" --account user@gmail.com
superhuman contact search "john" --account user@company.com
How it works: The CLI extracts OAuth tokens directly from Superhuman and makes API calls to Gmail or Microsoft Graph. Tokens are cached to disk with automatic background refresh when expiring.
Token Management
superhuman account auth
Tokens are stored in ~/.config/superhuman-cli/tokens.json and automatically refreshed using OAuth refresh tokens when they expire (within 5 minutes of expiry). No CDP connection is needed for token refresh.
Composing Email
Recipients can be specified as email addresses or contact names. Names are automatically resolved to email addresses via contact search.
superhuman draft create --to user@example.com --subject "Hello" --body "Hi there!"
superhuman draft create --to "john" --subject "Hello" --body "Hi there!"
superhuman draft list
superhuman draft list --account user@example.com
superhuman send --to user@example.com --subject "Quick note" --body "FYI"
superhuman reply <thread-id> --body "Thanks!"
superhuman reply <thread-id> --body "Thanks!" --send
superhuman reply-all <thread-id> --body "Thanks everyone!"
superhuman forward <thread-id> --to colleague@example.com --body "FYI"
superhuman draft update <draft-id> --body "Updated content"
superhuman draft delete <draft-id>
superhuman draft delete <draft-id1> <draft-id2>
superhuman send --draft <draft-id>
superhuman draft send <draft-id> --account=user@example.com --to=recipient@example.com --subject="Subject" --body="Body"
Draft Sources
The draft list command shows drafts from multiple sources with a "Source" column:
| Source | Description | Example ID |
|---|
native | Superhuman-only drafts | draft00ce4679cc58a64c |
gmail | Synced to Gmail | Gmail message ID |
outlook | Synced to Outlook | Outlook message ID |
Native Superhuman drafts (IDs starting with draft00...) are fetched from Superhuman's backend API and only exist in Superhuman. Provider-synced drafts are fetched from Gmail/Outlook APIs and are visible in native email clients.
Drafts Limitation
Drafts created via draft create use native Gmail/Outlook APIs, not Superhuman's proprietary draft system. This means:
| Where | Visible? |
|---|
| Native Gmail/Outlook web | Yes |
| Native mobile apps | Yes |
| Superhuman UI | No |
This is acceptable for CLI workflows where you iterate on drafts with LLMs and send via --send flag. If you need to edit in Superhuman UI, open the draft in native Gmail/Outlook first.
Managing Threads
superhuman archive <thread-id>
superhuman archive <thread-id1> <thread-id2>
superhuman delete <thread-id>
superhuman mark read <thread-id>
superhuman mark unread <thread-id>
superhuman star add <thread-id>
superhuman star remove <thread-id>
superhuman star list
superhuman snooze set <thread-id> --until tomorrow
superhuman snooze set <thread-id> --until next-week
superhuman snooze set <thread-id> --until "2024-02-15T14:00:00Z"
superhuman snooze cancel <thread-id>
superhuman snooze list
Snippets
Reusable email templates stored in Superhuman. Snippets support template variables like {first_name}.
superhuman snippet list
superhuman snippet list --json
superhuman snippet use "zoom link" --to user@example.com
superhuman snippet use "share recordings" --to user@example.com --vars "date=Feb 5,student_name=Jane"
superhuman snippet use "share recordings" --to user@example.com --vars "date=Feb 5" --send
Labels
superhuman label list
superhuman label get <thread-id>
superhuman label add <thread-id> --label Label_123
superhuman label remove <thread-id> --label Label_123
Attachments
superhuman attachment list <thread-id>
superhuman attachment download <thread-id>
superhuman attachment download <thread-id> --output ./downloads
superhuman attachment download --attachment <attachment-id> --message <message-id> --output ./file.pdf
Calendar
Superhuman has built-in calendar support, but prefer morgen CLI for calendar operations — it supports proper calendar filtering. See the morgen skill.
Options
| Option | Description |
|---|
--account <email> | Account to operate on (default: current account) |
--to <email|name> | Recipient email or name (names auto-resolved via contacts) |
--cc <email|name> | CC recipient (can be used multiple times) |
--bcc <email|name> | BCC recipient (can be used multiple times) |
--subject <text> | Email subject |
--body <text> | Email body (plain text, converted to HTML) |
--html <text> | Email body as raw HTML |
--send | Send immediately instead of saving draft (for reply/reply-all/forward/snippet) |
--vars <pairs> | Template variable substitution: "key1=val1,key2=val2" (for snippet use) |
--draft <id> | Draft ID to send (for send command) |
--label <id> | Label ID (for label add/remove) |
--until <time> | Snooze until time: preset or ISO datetime |
--output <path> | Output path for downloads |
--attachment <id> | Specific attachment ID |
--message <id> | Message ID (required with --attachment) |
--limit <number> | Number of results (default: 10) |
--include-done | Search all emails including archived (for search) |
--context <number> | Number of messages to show full body (default: all, for read) |
--json | Output as JSON |
--port <number> | CDP port (default: 9400) |
Common Workflows
Triage Inbox
superhuman inbox --limit 20
superhuman read <thread-id> --account user@gmail.com
superhuman archive <thread-id1> <thread-id2>
superhuman snooze set <thread-id> --until tomorrow
superhuman star add <thread-id>
Reply to Email
For drafting replies (recommended — lets the user review before sending):
superhuman read <thread-id> --account user@gmail.com
superhuman reply <thread-id> --body "Thanks for the update."
For sending replies immediately:
superhuman reply <thread-id> --body "Thanks for the update." --send
If superhuman reply fails (e.g. MS Graph 400 error on Outlook accounts), use the AI approach:
superhuman ai <thread-id> "draft a professional reply saying thanks for the update"
Search and Process
superhuman search "from:boss@company.com" --limit 10
superhuman search "is:unread has:attachment"
superhuman search "from:anthropic" --include-done
Multi-Account
superhuman account list
superhuman account switch work@company.com
superhuman contact search "john" --account personal@gmail.com
Snippets
superhuman snippet list
superhuman snippet use "meeting invite" --to colleague@example.com --vars "date=Feb 10" --send
Snooze Presets
| Preset | When |
|---|
tomorrow | 9am next day |
next-week | 9am next Monday |
weekend | 9am Saturday |
evening | 6pm today |
| ISO datetime | Exact time (e.g., 2024-02-15T14:00:00Z) |
Output Formats
Most commands support --json for structured output:
superhuman inbox --json | jq '.[] | {id, subject, from}'
Troubleshooting
Token Expired
superhuman account auth
Tokens auto-refresh. If refresh fails: Token for user@email.com expired. Run 'superhuman account auth' to re-authenticate.
Connection Failed
- Check if Superhuman is installed at
/Applications/Superhuman.app
- Launch with debugging:
/Applications/Superhuman.app/Contents/MacOS/Superhuman --remote-debugging-port=9400
- Verify:
superhuman status
From a container: Ensure CDP_HOST=host.docker.internal is set and the container was started with --add-host=host.docker.internal:host-gateway. The CLI skips local app launch when CDP_HOST is non-localhost.
Thread Not Found
Thread IDs come from inbox/search. Use --json to get exact IDs:
superhuman inbox --json | jq '.[0].id'
How It Works
Direct API (Primary)
Most operations use direct Gmail API and Microsoft Graph API calls with cached OAuth tokens:
| Operation | Gmail API | MS Graph API |
|---|
| List inbox | GET /messages?q=label:INBOX | GET /mailFolders/Inbox/messages |
| Search | GET /messages?q=... | GET /messages?$search=... |
| Labels | POST /threads/{id}/modify | PATCH /messages/{id} |
| Read status | Add/remove UNREAD label | PATCH /messages/{id} with isRead |
| Archive | Remove INBOX label | POST /messages/{id}/move |
| Star | Add STARRED label | PATCH /messages/{id} with flag |
| Attachments | GET /messages/{id}/attachments/{id} | GET /messages/{id}/attachments/{id} |
| Contacts | Google People API | MS Graph People API |
| Snippets | Superhuman backend API | Superhuman backend API |
OAuth tokens (including refresh tokens) are extracted from Superhuman and cached to disk. When tokens expire, they are automatically refreshed via OAuth endpoints without requiring CDP connection.
CDP (Secondary)
Chrome DevTools Protocol is only needed for:
account auth — One-time token extraction from window.GoogleAccount (also stores AI user prefix)
status — Check Superhuman connection
search / inbox (when no cached tokens) — Fallback via Superhuman's portal API
All other operations (read, reply, forward, draft, archive, delete, labels, star, snooze, attachments, contacts, snippets) use direct API with cached tokens.
Benefits
- Reliability: Direct API calls don't depend on Superhuman's UI state
- Speed: No CDP round-trips for most operations
- Offline from CDP: After initial
account auth, most operations work without CDP
- Multi-account: Cached tokens enable operating on any linked account
Supports both Gmail and Microsoft/Outlook accounts.