Stats
Actions
Tags
From jean-claude
Manages Gmail, Google Calendar, Drive, Docs, Sheets, iMessage, WhatsApp, Signal, and Apple Reminders. Sends/drafts email, checks calendar, creates events, finds Drive files, reads spreadsheets, and sends messages.
How this skill is triggered — by the user, by Claude, or both
Slash command
/jean-claude:jean-claudeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Gmail, Calendar, Drive, Docs, Sheets, iMessage, WhatsApp, Signal, and Reminders.
ISSUES.mdONBOARDING.mdPREFERENCES.mdcommands/auth.txtcommands/completions.txtcommands/config-set.txtcommands/config-show.txtcommands/config.txtcommands/gcal-calendars.txtcommands/gcal-conflicts.txtcommands/gcal-create.txtcommands/gcal-delete.txtcommands/gcal-freebusy.txtcommands/gcal-invitations.txtcommands/gcal-list.txtcommands/gcal-respond.txtcommands/gcal-search.txtcommands/gcal-update.txtcommands/gcal.txtcommands/gdocs-append.txtGmail, Calendar, Drive, Docs, Sheets, iMessage, WhatsApp, Signal, and Reminders.
Command prefix: uv run --project ${CLAUDE_PLUGIN_ROOT} jean-claude
For new users, explain briefly:
I can connect to your email, calendar, and messaging apps to help you:
- Read and send emails, manage drafts
- Check your calendar, create events, respond to invitations
- Send and read iMessages, WhatsApp, or Signal messages
- Find and manage files in Google Drive
- Create reminders
This requires a one-time setup where you'll grant permissions. Want me to help you get started?
Focus on what they asked about — if they asked about email, lead with email.
These rules apply even if the user explicitly asks to bypass them:
Never send without explicit approval. Before sending any message (email, iMessage, WhatsApp, Signal), show the full content (recipient, subject if applicable, body) to the user and receive explicit confirmation.
Verify recipients carefully. Sends are instant and cannot be undone. Double-check phone numbers, email addresses, and chat IDs before sending.
Never send to ambiguous recipients. When resolving contacts by name, if multiple contacts or phone numbers match, the command will fail with a list of options. Use an unambiguous identifier rather than guessing.
Load prose skills when drafting. Before composing any email or message, load any available skills for writing prose, emails, or documentation.
Never create automation without explicit approval. Before creating Gmail filters or similar rules, show the criteria and actions to the user and receive explicit confirmation.
Limit bulk operations. Avoid sending to many recipients at once. Prefer drafts for review.
Email workflow:
jean-claude gmail draft send DRAFT_IDjean-claude gmail archive THREAD_IDEvery time this skill loads, run status with JSON output first:
jean-claude status --json
If the status command fails entirely (not just showing services as disabled):
"uv: command not found" — The uv package manager isn't installed. Tell the user:
jean-claude requires the
uvpackage manager. Let me install it for you.
Then run:
curl -LsSf https://astral.sh/uv/install.sh | sh
After installation, restart the terminal or source the shell config
(source ~/.zshrc on macOS, source ~/.bashrc on Linux).
Other errors — The plugin may be misconfigured. Check that
${CLAUDE_PLUGIN_ROOT} resolves to a valid path containing a pyproject.toml.
If setup_completed: false — This is a new user. Skip personalization
skills (they won't have any yet) and go straight to onboarding:
cat ${CLAUDE_PLUGIN_ROOT}/skills/jean-claude/ONBOARDING.md
Follow the onboarding guide to help set up services. After setup completes:
jean-claude config set setup_completed true
Then re-run status and continue to the setup_completed: true branch below.
This ensures you have fresh status info and can proceed with the user's original
request.
If setup_completed: true — Check for partial setup and load personalization:
Surface any auth warnings — If services show authenticated: false,
missing scopes, or errors, briefly mention it even if unrelated to the
user's request. Don't derail—just note the issue and offer to fix later:
"By the way, your Google Contacts permission is missing — I can't show contact names in emails. Want me to help fix that after your request?"
Check for missing services — If the user asks for a service that shows
authenticated: false or enabled: false, guide them through just that
service's setup from ONBOARDING.md. After partial setup completes, continue
to step 3.
Load personalization skills — Check if user skills like managing-messages
exist (look at available skills for anything mentioning inbox, email, message,
or communication). If found, load them—user preferences override defaults.
Offer to create preferences — If no personalization skill was found in step 3, offer to create one after completing the user's immediate request. See PREFERENCES.md for the creation flow. Don't interrupt the user's task—help them first, then offer.
Proceed with the user's request — Execute whatever task prompted loading this skill (check inbox, send message, etc.).
Load the platform guide before using any messaging commands. Each platform has different commands and options. Gmail is documented in this file, but messaging platforms have separate guides:
# Load before using iMessage
cat ${CLAUDE_PLUGIN_ROOT}/skills/jean-claude/platforms/imessage.md
# Load before using WhatsApp
cat ${CLAUDE_PLUGIN_ROOT}/skills/jean-claude/platforms/whatsapp.md
# Load before using Signal
cat ${CLAUDE_PLUGIN_ROOT}/skills/jean-claude/platforms/signal.md
Don't guess command syntax — each platform is different. iMessage and WhatsApp have different flags and subcommands despite similar functionality.
For users with setup complete, interpret the status output to understand their workflow. Run human-readable status if needed for counts:
jean-claude status
Gmail:
Calendar:
Reminders:
Messaging:
Apple services (Contacts, iMessage, Reminders): These are disabled by default.
If enabled: false in status, enable with:
jean-claude config set enable_contacts true # For iMessage name lookup
jean-claude config set enable_imessage true
jean-claude config set enable_reminders true
Once enabled, status checks full permissions (may trigger macOS permission dialogs on first run). If permission is missing, guide the user through System Settings > Privacy & Security > Automation.
Summaries become stale immediately. Once you present an inbox summary, that snapshot is already potentially outdated. State changes constantly:
Verify before making claims. When the user asks about current state — "did I reply?", "is that still unread?", "how many are left?" — re-check rather than relying on your memory of earlier summaries. Your memory is of what was true when you last checked, not what's true now.
User: "Did I reply to the Acme email?"
Agent: recalls earlier summary where it wasn't replied to
"No, that thread is still waiting for your reply."
User: "Did I reply to the Acme email?"
Agent: searches for sent messages to Acme
"Yes — you replied today at 12:27pm following up on their question."
Re-fetch when:
General principle: Verify claims from the source. Re-fetching is cheap; wrong information is expensive.
# Check full inbox state (total count, all threads)
jean-claude gmail inbox
# Check recent emails only (useful for "what's new")
jean-claude gmail inbox --since yesterday
# Check sent messages to verify replies
jean-claude gmail search "in:sent to:[email protected]" -n 5
# Re-fetch iMessage (see platforms/imessage.md for full docs)
jean-claude imessage messages --unread
# Re-sync WhatsApp for message updates
jean-claude whatsapp messages --unread
Choosing between filtered and full inbox:
--since yesterday — Use for "what's new" or daily triage. Shows recent
arrivals only. After archiving these, there may still be older emails in inbox.User personalization skills override these defaults. If no personalization skill exists, use these behaviors:
When showing messages (inbox, unread, search results), group by category and use group-letter numbering so the user can reference items individually ("archive A1", "reply to B2") or by group ("archive all of C", "archive B1-B3").
Group-letter numbering. Pick a small set of categories (typically 3–5) that fit the messages at hand — common ones are Needs attention, Travel / receipts, Newsletters, In progress. Label each group with a letter (A, B, C, ...) and number items within the group starting at 1:
**Needs attention:**
A1: Flo critical alert — water shutoff at the main valve
A2: Zach Perret (yesterday) — Invite to dinner Thursday
**Travel & receipts:**
B1: Delta (today at 10:37 AM) — LAX → TUS trip details Apr 22
B2: Waymo (yesterday) — Ride receipts (4 messages)
**Newsletters:**
C1: The Economist (today) — Weekly edition
C2: The Browser (today) — Sunday Supplement
Use manual N: formatting, not markdown lists. Markdown numbered lists
auto-correct to be sequential — if you write "3. 4. 5. 7. 15. 16." the renderer
displays "3. 4. 5. 6. 7. 8." causing a mismatch between what you wrote and what
the user sees. The A1: / B2: form sidesteps the renderer entirely.
Keep items compact — no blank lines between them. Blank lines waste vertical space and make the list harder to scan. Items within a group should be on consecutive lines; one blank line separates groups.
Preserve identifiers through the session. After archiving A1 and A3, show the remaining items as A2, A4, A5 — don't renumber. This gives items stable identifiers across operations.
Always include dates conversationally. Check today's date before formatting:
date "+%Y-%m-%d %H:%M %Z" # Current date/time for reference
Date formatting rules:
Example (assuming today is Sunday, Dec 29):
**Needs attention:**
A1: Jordan Lee (Nov 15) — Forwarded: Fellowship nomination, asks for response by Jan 5
A2: Squarespace (yesterday at 9:15 AM) — Domain transfer rejected for maxroos.com
**Receipts & confirmations:**
B1: DoorDash (35 min ago) — Your order from Superba
B2: GitHub (Friday at 4:30 PM) — PR merged: fix-auth-flow
**Newsletters:**
C1: Goodreads (today at 10:30 AM) — Book newsletter
Never fabricate details not present in the data.
Read multi-message threads before summarizing. The inbox response only
contains metadata and the latest message's snippet. For threads with multiple
messages, read the thread (gmail thread THREAD_ID) to know what the other
messages actually say. Never infer thread content from the snippet alone.
Bad: "3-message thread — likely includes Effie's reply" Good: reads thread first → "Kristin nominated Effie; Effie replied accepting and asking about travel logistics; Kristin confirmed hotel is covered"
When uncertain, say so: "The email doesn't specify who the assessment is for."
Use the total_threads and total_unread fields from the inbox response.
The inbox command returns accurate counts from Gmail's label stats:
{"total_threads": 32, "total_unread": 28, "threads": [...]}
When reporting counts, use these fields — not the number of threads returned.
The -n flag limits how many threads are fetched, not how many exist.
Prefer --since over -n for complete results. If you need emails from
today, use --since today rather than -n 20. The -n flag returns the
N most recent threads but may miss older unread emails in the inbox.
The --since flag accepts human-readable dates like "yesterday", "3 days ago",
"last week", or explicit dates like "2026-01-21".
When --since or --unread is used, the threads array is a subset of
the full inbox. The total_threads and total_unread fields still reflect the
full inbox, not the filtered results.
Report filtered results accurately:
Never claim "inbox cleared" after archiving filtered results. If you
archived 6 threads from --since yesterday and total_threads was 32, there
are still 26 other threads in the inbox. To check true inbox state after
triaging recent emails, run jean-claude gmail inbox without filters.
Hallucinated details erode trust. The user can't distinguish fabrications from real data.
Show the full email text (not a summary) when:
Summaries are appropriate when:
The test: If the user might need to quote, reference, or respond to the exact wording, show the full text. If they just need to understand the gist, summarize.
When showing the full text of an email, include all relevant headers:
From: Sender Name <[email protected]>
To: Recipient <[email protected]>
Date: Yesterday at 9:54 PM
Subject: Meeting follow-up
[email body]
Always include:
Include when present:
The To field helps the user understand context — was this sent directly to them, to a group, or forwarded from somewhere else?
User: "Reply to Alex's email and say I can't make it"
Agent: reads email, immediately drafts reply
"Alex's email was about NY logistics. Draft reply:
Hi Alex, Unfortunately I won't be able to join..."
User: "Reply to Alex's email and say I can't make it"
Agent: reads email, shows it first
"From: Alex Chen [email protected] To: Max [email protected] Date: Sunday at 9:34 PM Subject: Re: Napa Trip Logistics
Hey- Sam is going to fly back on Friday with Jordan and me. Same itinerary as Jordan all the way back to LA. please let the office know. Also she'll stay in the second bedroom at the hotel. Can you let them know? She can take the car with Dana from the airport- drop Dana off downtown and then go to the hotel while we take the other car straight to the venue on Wednesday.
Draft reply:
Hi Alex, ..."
When you show the full body of a message — not just a snippet from a list —
mark it as read. The gmail message and gmail thread commands print a
reminder with the exact command to run.
Don't mark as read when only showing inbox/search results (snippets).
Cross-service commands:
jean-claude gmail mark-read THREAD_IDjean-claude imessage mark-read CHAT_IDjean-claude whatsapp mark-read CHAT_IDAlways cross-reference between email and calendar. When processing messages, check if they relate to calendar events. When reviewing calendar, check email for relevant context.
Messages → Calendar:
1. Dana Chen (today at 10:33 AM) — "Please call Marcus at 415-555-0142"
→ You have his number for the 11:30 call.
1. Dana Chen (today at 10:33 AM) — "Please call Marcus at 415-555-0142"
→ You have "Call with Marcus" at 11:30. Want me to add his number to the invite?
1. Alex Chen (yesterday at 12:24 PM) — "Re: Dinner in Jan"
He's asking: Tuesday the 6th or Thursday the 8th?
1. Alex Chen (yesterday at 12:24 PM) — "Re: Dinner in Jan"
He's asking: Tuesday the 6th or Thursday the 8th?
→ You're free both evenings. Thursday has a 3pm meeting that ends at 4.
Calendar → Email:
When reviewing calendar events, check email for related context:
The user shouldn't have to ask "what's on my calendar?" or "did they send details?" as follow-ups. If a message relates to a scheduled event, check the calendar proactively. Check calendars where the user has events (see "Choosing the Right Calendar").
Complete tasks fully. Don't stop early to ask if you should continue.
Proceed through Terms of Service, cookie banners, login confirmations, and "Continue" buttons without asking — these are prerequisites, not decisions.
Ask only for: purchases, sending messages, creating public content, or sharing data with new parties.
The test: Would a reasonable person pause here?
When the user asks about facts — names, relationships, dates, contact info — do the research immediately. Don't say "I don't know" based on limited context.
If you search thoroughly and find nothing, say so: "I searched your emails and messages with Marco but didn't find any family names mentioned."
User: "What are Marco's wife & kid's names?"
Agent: "I don't know—the message from Marco didn't mention names. Want me to search your emails or messages for more context?"
User: "What are Marco's wife & kid's names?"
Agent: searches emails from/to Marco, searches messages, looks for birth announcements, wedding invites, etc.
"From your email history with Marco:
When the user asks to read something, include all related content:
Don't stop at metadata. "Want me to download the attachment?" is asking the user to do your job.
User: "read the amex email"
Agent: fetches email metadata
"The AMEX email has a PDF attachment (claim_docs.pdf, 28KB). Want me to download it?"
User: "read the amex email"
Agent: fetches email, downloads PDF, reads it
"AMEX sent claim documents for #12266792. The PDF contains:
Two subsections, two audiences:
Composition principles live in a separate file that the composer subagent reads directly:
${CLAUDE_PLUGIN_ROOT}/skills/jean-claude/composition-principles.md
Contains writing principles, examples, and the self-critique process. The subagent reads this file itself — no need to paste it into the prompt.
What the main agent handles: research, recipient mechanics, spawning the composer, creating the Gmail draft, and iterating with the user.
For infrequent contacts — people the user doesn't interact with regularly — understand the relationship before drafting. Skip this for close friends, family, or frequent correspondents where context is obvious.
When replying to an infrequent contact (catching up, introductions, social correspondence), research before drafting:
User: "Reply to Alex's email"
Agent: immediately drafts reply
"Draft: Hi Alex, Thanks for reaching out! The AI coding tool sounds right up my alley. Happy to connect with Jordan. Best, Max"
User: "Reply to Alex's email"
Agent: searches email history and web
"Alex Chen — based in SF, you last emailed him 8 months ago about the open-source project. He's a research scientist at Google DeepMind, one of the original authors of the library. Before that you collaborated on a NeurIPS tutorial in 2019.
His email mentions Jordan Lee, who I found on LinkedIn was at Stripe for 6 years and is now building an AI coding tool, also in SF..."
[Then proceeds to draft with this context]
The user shouldn't need to ask "when did I last talk to them?" or "who is this person?" — do that research proactively.
When replying to an introduction email, move the introducer to BCC. The body text ("BCCing X to spare their inbox") is covered in Composition Principles above — this section covers the mechanics:
# Create reply, then move introducer to BCC
cat << 'EOF' | jean-claude gmail draft reply MESSAGE_ID
BCCing Alex to spare their inbox.
[Rest of reply]
EOF
jean-claude gmail draft update DRAFT_ID \
--bcc "[email protected]" < /dev/null
Sometimes the user wants to reply in-thread but send it to someone other than the original sender — typically moving the sender to CC. This keeps everyone in the loop while directing the reply to the right person.
When to apply: The user says something like:
Pattern: Create the reply, then update recipients:
# Step 1: Create reply (preserves threading, quotes original)
cat << 'EOF' | jean-claude gmail draft reply MESSAGE_ID
Your message here.
EOF
# Step 2: Update recipients
jean-claude gmail draft update DRAFT_ID \
--to "[email protected]" --cc "[email protected]" < /dev/null
Alex sends an email to his assistant Dana at Sequoia, CC'ing the user:
"Dana - Max will join us for the partners retreat in Napa. Please book him on the Friday flight."
User says: "Reply to Dana that I can't make it, CC Alex"
jean-claude gmail draft reply MESSAGE_ID with the bodyjean-claude gmail draft update DRAFT_ID --to "[email protected]" --cc "[email protected]"jean-claude gmail draft get DRAFT_ID to verify recipients, show to userjean-claude gmail draft send DRAFT_ID after approvalEmail quality is the single most important thing jean-claude does. A bad email damages a real relationship. Drafting deserves a dedicated context window — not a few tokens squeezed between tool calls and inbox state.
When to use a subagent:
When to skip the subagent:
Use the Task tool with subagent_type: "general-purpose". The subagent's job
is to write the email body — nothing else. It doesn't call CLI commands, create
drafts, or interact with the user.
What to include in the subagent prompt:
File paths — Tell the subagent to read these files before writing:
${CLAUDE_PLUGIN_ROOT}/skills/jean-claude/composition-principles.md —
writing principles, examples, and self-critique process~/.claude/skills/managing-messages/SKILL.md
or whatever exists in ~/.claude/skills/) — this is the most important
input. Without it, the subagent will write generic emails. If no
personalization skill exists, note this to the user.The conversation context — The full original message or thread the user is replying to. Not a summary — the actual text, so the subagent can match tone and reference specifics.
Relationship context — What you learned from research: when they last corresponded, who this person is, shared history. For frequent contacts, a brief note ("close friend, casual tone") suffices.
What the user wants to say — Their intent, in their words if possible. "Decline the invitation but keep the door open" or "Accept and suggest meeting for coffee when I'm in SF."
User says: "Reply to Alex's email about the intro to Jordan"
You've already researched: Alex is a DeepMind researcher, last corresponded 8 months ago about an open-source project, Jordan is building an AI coding tool.
You are drafting an email. Read these files first, then write the email body.
Read these files:
- /path/to/jean-claude/skills/jean-claude/composition-principles.md
- ~/.claude/skills/managing-messages/SKILL.md (email composition section)
## Context
Replying to Alex Chen (DeepMind research scientist, SF). Last corresponded
8 months ago about the open-source project. Before that, collaborated on a
NeurIPS tutorial in 2019.
Alex's email:
[Full text of Alex's message]
## What the user wants to say
Accept the intro to Jordan, express interest in the AI coding tool.
For important correspondence — first contact with someone significant, sensitive topics, emails where tone really matters — add a second critique after the subagent returns its draft.
Read the draft yourself and ask: Does this sound like the user? Check it against their style guide. Look for:
If something's off, spawn the subagent again with the draft and specific feedback ("too formal — rewrite the opening more casually" or "the sign-off should be just the name, no 'Best'"). Iterate until it reads right.
This mirrors the code review convergence pattern: compose → critique → revise → present. One pass catches most issues. Two catches subtle ones.
Take the email body and create the Gmail draft, then proceed to "Iterating with the User" below.
For substantive emails, briefly explain your tone choices when presenting the draft: "Went warm and brief since you haven't talked in 8 months — want something more formal?" This lets the user steer before committing.
Create actual Gmail drafts, not just text in the conversation. Drafts persist if the session ends and can be edited in Gmail directly.
Workflow:
jean-claude gmail draft create (or reply/forward)cat ~/.cache/jean-claude/drafts/draft-DRAFT_ID.txt to see currentcat ... | jean-claude gmail draft update DRAFT_ID to saveThis plugin requires uv (Python package manager). If not installed:
curl -LsSf https://astral.sh/uv/install.sh | sh
Credentials stored in ~/.config/jean-claude/. First-time setup:
# Full access (read, send, modify)
jean-claude auth
# Or read-only access (no send/modify capabilities)
jean-claude auth --readonly
# Check authentication status and API availability
jean-claude status
# Log out (remove stored credentials)
jean-claude auth --logout
This opens a browser for OAuth consent. Credentials persist until revoked.
If you see "This app isn't verified": This warning appears because jean-claude uses a personal OAuth app that hasn't gone through Google's (expensive) verification process. It's safe to proceed:
The "unsafe" label just means unverified, not malicious. The app only accesses the specific Google services you authorize.
To use your own Google Cloud credentials instead (if default ones hit the 100
user limit), download your OAuth JSON from Google Cloud Console and save it as
~/.config/jean-claude/client_secret.json before running the auth script. See
README for detailed setup steps.
WhatsApp and Signal are disabled by default. These services require compiling native binaries (Go for WhatsApp, Rust for Signal), and we want jean-claude to work smoothly for Gmail/Calendar users without those toolchains. Enable explicitly if you need messaging:
jean-claude config set enable_whatsapp true
jean-claude config set enable_signal true
The status command shows whether each service is enabled or disabled.
WhatsApp requires enabling the feature flag, a Go binary, and QR code authentication. First-time setup:
# Build the Go CLI (requires Go installed)
cd ${CLAUDE_PLUGIN_ROOT}/whatsapp && go build -o whatsapp-cli .
# Authenticate with WhatsApp (scan QR code with your phone)
jean-claude whatsapp auth
# Check authentication status
jean-claude status
The QR code will be displayed in the terminal and saved as a PNG file. Scan it with WhatsApp: Settings > Linked Devices > Link a Device.
Credentials are stored in ~/.config/jean-claude/whatsapp/. To log out:
jean-claude whatsapp logout
Signal requires enabling the feature flag, a Rust binary, and QR code linking. First-time setup:
# Build the Rust CLI (requires Rust/Cargo and protobuf installed)
cd ${CLAUDE_PLUGIN_ROOT}/signal && cargo build --release
# Link as a secondary device (scan QR code with your phone)
jean-claude signal link
# Check authentication status
jean-claude status
The QR code will be displayed in the terminal. Scan it with Signal on your phone: Settings > Linked Devices > Link New Device.
Credentials are stored in ~/.local/share/jean-claude/signal/.
CLI convention: Email addresses are comma-separated (--to "[email protected],[email protected]").
Other multi-value flags use repeated flags (--attach f1 --attach f2).
See "Personalization" section for default behaviors and user skill overrides.
Two data types:
inbox.search and get.Thread response schema (from inbox):
{
"threads": [
{
"threadId": "19b29039fd36d1c1",
"messageCount": 3,
"unreadCount": 1,
"subject": "Subject line",
"labels": ["INBOX", "UNREAD"],
"messages": [
{"id": "msg_id_1", "date": "2025-12-14T10:00:00-08:00", "from": "[email protected]", "to": "[email protected]", "labels": ["INBOX"], "unread": false},
{"id": "msg_id_2", "date": "2025-12-15T14:30:00-08:00", "from": "[email protected]", "to": "[email protected]", "labels": ["SENT"], "unread": false},
{"id": "msg_id_3", "date": "2025-12-16T09:00:00-08:00", "from": "[email protected]", "to": "[email protected]", "labels": ["INBOX", "UNREAD"], "unread": true}
],
"latest": {
"id": "msg_id_3",
"date": "2025-12-16T09:00:00-08:00",
"from": "[email protected]",
"snippet": "Latest message snippet..."
},
"file": "~/.cache/jean-claude/emails/thread-19b29039fd36d1c1.json"
}
],
"nextPageToken": "abc123..."
}
Thread files contain metadata only (no message bodies). The messages array
shows each message with date, sender, and read status — ordered oldest to newest.
The latest object provides quick access to the most recent message's metadata and
snippet. To read message bodies, use gmail message MESSAGE_ID or gmail thread THREAD_ID.
Message response schema (from search):
{
"messages": [
{
"id": "19b29039fd36d1c1",
"threadId": "19b29039fd36d1c1",
"from": "Name <[email protected]>",
"to": "[email protected]",
"subject": "Subject line",
"date": "2025-12-16T21:12:21-08:00",
"snippet": "First ~200 chars of body...",
"labels": ["INBOX", "UNREAD"],
"file": "~/.cache/jean-claude/emails/email-19b29039fd36d1c1.json"
}
],
"nextPageToken": "abc123..."
}
get returns a list directly (no pagination wrapper):
[
{
"id": "19b29039fd36d1c1",
"threadId": "19b29039fd36d1c1",
"from": "Name <[email protected]>",
...
"file": "~/.cache/jean-claude/emails/email-19b29039fd36d1c1.json"
}
]
Message file format: Each message creates three files:
email-{id}.json — Metadata with body_file and html_file pathsemail-{id}.txt — Plain text body (readable with cat/less)email-{id}.html — HTML body when present (contains unsubscribe links)The nextPageToken field is only present when more results are available. Use
--page-token to fetch the next page:
# First page
jean-claude gmail search "is:unread" -n 50
# If nextPageToken is in the response, fetch next page
jean-claude gmail search "is:unread" -n 50 \
--page-token "TOKEN_FROM_PREVIOUS_RESPONSE"
# Inbox emails from a sender
jean-claude gmail search "in:inbox from:[email protected]"
# Limit results with -n
jean-claude gmail search "from:[email protected]" -n 10
# Unread inbox emails
jean-claude gmail search "in:inbox is:unread"
# Shortcut for inbox (includes total_threads and total_unread counts)
jean-claude gmail inbox
jean-claude gmail inbox --unread
# Use --since for complete results from a date (preferred over -n)
# Accepts human-readable dates like "yesterday", "last week", "3 days ago"
jean-claude gmail inbox --since yesterday
jean-claude gmail inbox --since "3 days ago"
jean-claude gmail inbox --since "last week"
jean-claude gmail inbox --since 2026-01-20
# -n limits results but may miss older emails - use --since instead
jean-claude gmail inbox -n 5
# Inbox also supports pagination
jean-claude gmail inbox --unread -n 50 --page-token "TOKEN"
Common Gmail search operators: in:inbox, is:unread, is:starred, from:,
to:, subject:, after:2025/01/01, has:attachment, label:
# Fetch message by ID (writes body to ~/.cache/jean-claude/emails/)
jean-claude gmail message MESSAGE_ID
# Fetch multiple messages
jean-claude gmail message MSG_ID_1 MSG_ID_2 MSG_ID_3
# Fetch all messages in a thread (full conversation)
jean-claude gmail thread THREAD_ID
Use this when you have a specific message ID and want to read its full content.
Mark as read after fetching. When you fetch unread messages, the command prints a reminder with the exact mark-read command to run:
To mark as read: jean-claude gmail mark-read THREAD_ID
Run that command after presenting the content to the user. This also applies when creating replies or forwards (you read the original to compose the response).
All draft commands read body from stdin. Create uses flags for metadata.
IMPORTANT: Use heredocs, not echo. Claude Code's Bash tool has a known bug that escapes exclamation marks ('!' becomes '!'). Always use heredocs:
# Create a new draft
cat << 'EOF' | jean-claude gmail draft create --to "[email protected]" --subject "Subject"
Message body here!
EOF
# Create with CC/BCC
cat << 'EOF' | jean-claude gmail draft create --to "[email protected]" --subject "Subject" --cc "[email protected]"
Multi-line message body here.
EOF
# Multiple recipients
cat << 'EOF' | jean-claude gmail draft create --to "[email protected],[email protected]" --subject "Team update"
Message to multiple people.
EOF
# Reply to a message (body from stdin, preserves threading, includes quoted original)
cat << 'EOF' | jean-claude gmail draft reply MESSAGE_ID
Thanks for your email!
EOF
# Reply with custom CC
cat << 'EOF' | jean-claude gmail draft reply MESSAGE_ID --cc "[email protected]"
Thanks for the update!
EOF
# Forward a message (TO as argument, optional note from stdin)
cat << 'EOF' | jean-claude gmail draft forward MESSAGE_ID [email protected]
FYI - see below!
EOF
# Forward without a note
jean-claude gmail draft forward MESSAGE_ID [email protected] < /dev/null
# Reply-all (includes all original recipients)
cat << 'EOF' | jean-claude gmail draft reply-all MESSAGE_ID
Thanks everyone!
EOF
# List drafts
jean-claude gmail draft list
jean-claude gmail draft list -n 5
# Get draft (writes metadata to .json and body to .txt)
jean-claude gmail draft get DRAFT_ID
# Update draft body (from stdin)
cat ~/.cache/jean-claude/drafts/draft-DRAFT_ID.txt | jean-claude gmail draft update DRAFT_ID
# Update metadata only
jean-claude gmail draft update DRAFT_ID --subject "New subject" --cc "[email protected]"
# Update both body and metadata
cat body.txt | jean-claude gmail draft update DRAFT_ID --subject "Updated"
# Send a draft (after approval)
jean-claude gmail draft send DRAFT_ID
# Delete a draft
jean-claude gmail draft delete DRAFT_ID
Draft creation commands (create, reply, reply-all, forward, update)
support --attach for file attachments. Use multiple times for multiple files:
# Create draft with attachments
cat << 'EOF' | jean-claude gmail draft create --to "[email protected]" --subject "Report" --attach report.pdf --attach data.csv
Please see the attached files.
EOF
# Reply with attachment
cat << 'EOF' | jean-claude gmail draft reply MESSAGE_ID --attach response.pdf
Here is my response with the requested document.
EOF
# Forward (original attachments included automatically)
cat << 'EOF' | jean-claude gmail draft forward MESSAGE_ID [email protected]
FYI - see below.
EOF
# Forward with additional attachment
cat << 'EOF' | jean-claude gmail draft forward MESSAGE_ID [email protected] --attach notes.pdf
FYI - I added my notes.
EOF
# Add attachment to existing draft (replaces any existing attachments)
jean-claude gmail draft update DRAFT_ID --attach newfile.pdf < /dev/null
# Remove all attachments from a draft
jean-claude gmail draft update DRAFT_ID --clear-attachments < /dev/null
Viewing attachments: Use draft get to see what files are attached:
jean-claude gmail draft get DRAFT_ID
# Output includes: {"attachments": [{"filename": "report.pdf", "mimeType": "application/pdf"}]}
Iterating on long emails: For complex emails, use file editing to iterate with the user without rewriting the full email each time:
jean-claude gmail draft get DRAFT_ID (writes .json and .txt)~/.cache/jean-claude/drafts/draft-DRAFT_ID.txtcat ~/.cache/jean-claude/drafts/draft-DRAFT_ID.txt | jean-claude gmail draft update DRAFT_IDVerifying important drafts: For important emails, read the draft back after creating it to confirm formatting is correct:
# Create draft
cat << 'EOF' | jean-claude gmail draft create --to "..." --subject "..."
Email body here!
EOF
# Verify the draft content (check for escaping issues like \!)
jean-claude gmail draft get DRAFT_ID
cat ~/.cache/jean-claude/drafts/draft-DRAFT_ID.txt
This catches any escaping bugs before sending. Also verify drafts with attachments — confirm the right files are attached before sending.
Most commands operate on threads (matching Gmail UI behavior). Use threadId from
inbox output. Star/unstar operate on individual messages (use IDs from messages array).
# Star/unstar (message-level - use message IDs from `messages` array)
jean-claude gmail star MSG_ID1 MSG_ID2 MSG_ID3
jean-claude gmail unstar MSG_ID1 MSG_ID2
# Archive/unarchive (thread-level - use threadId)
jean-claude gmail archive THREAD_ID1 THREAD_ID2 THREAD_ID3
jean-claude gmail archive --query "from:[email protected]" -n 50
jean-claude gmail unarchive THREAD_ID1 THREAD_ID2 THREAD_ID3
# Mark read/unread (thread-level - use threadId)
jean-claude gmail mark-read THREAD_ID1 THREAD_ID2
jean-claude gmail mark-unread THREAD_ID1 THREAD_ID2
# Trash (thread-level - use threadId)
jean-claude gmail trash THREAD_ID1 THREAD_ID2 THREAD_ID3
# Modify labels (thread-level - add/remove any label)
jean-claude gmail modify-labels THREAD_ID --add SPAM --remove INBOX
jean-claude gmail modify-labels THREAD_ID1 THREAD_ID2 --add STARRED
jean-claude gmail modify-labels THREAD_ID --remove UNREAD
Spam: Use modify-labels --add SPAM --remove INBOX to report spam. Unlike
trash, this trains Gmail's spam filter for future messages from that sender.
Which ID to use:
gmail thread): use threadIdgmail message, reply): use id from messages array--query for pattern-based operations (archive supports this)# List attachments for a message
jean-claude gmail attachments MESSAGE_ID
# Download an attachment (saved to ~/.cache/jean-claude/attachments/)
jean-claude gmail attachment-download MESSAGE_ID ATTACHMENT_ID filename.pdf
# Download to specific directory
jean-claude gmail attachment-download MESSAGE_ID ATTACHMENT_ID filename.pdf --output ./
Unsubscribe links are in the HTML file, not the plain text. Note: HTML files are only created when the email has HTML content (most newsletters do).
# Search HTML body for unsubscribe links (if HTML file exists)
grep -oE 'https?://[^"<>]+unsubscribe[^"<>]*' ~/.cache/jean-claude/emails/email-MESSAGE_ID.html
Decoding tracking URLs: Newsletters often wrap links in tracking redirects. URL-decode to get the actual destination:
import urllib.parse
print(urllib.parse.unquote(encoded_url))
Completing the unsubscribe:
List all Gmail labels to get label IDs for filtering:
jean-claude gmail labels
Returns system labels (INBOX, SENT, TRASH, etc.) and custom labels (Label_123...).
Filters automatically process incoming mail based on criteria.
# List all filters
jean-claude gmail filter list
# Get a specific filter
jean-claude gmail filter get FILTER_ID
# Delete a filter
jean-claude gmail filter delete FILTER_ID
Creating filters — query + label operations:
# Archive (remove INBOX label)
jean-claude gmail filter create \
"to:[email protected]" -r INBOX
# Star and mark important
jean-claude gmail filter create \
"from:[email protected]" -a STARRED -a IMPORTANT
# Mark as read (remove UNREAD label)
jean-claude gmail filter create \
"from:[email protected]" -r UNREAD
# Forward
jean-claude gmail filter create \
"from:[email protected]" -f [email protected]
Common labels: INBOX, UNREAD, STARRED, IMPORTANT, TRASH, SPAM,
CATEGORY_PROMOTIONS, CATEGORY_SOCIAL, CATEGORY_UPDATES
Custom labels: Use jean-claude gmail labels to get IDs like Label_123456.
All calendar commands return JSON.
By default, commands operate on the primary calendar. Use --calendar to work
with other calendars.
# List available calendars
jean-claude gcal calendars
Returns:
[
{"id": "[email protected]", "name": "Personal", "primary": true, "accessRole": "owner"},
{"id": "[email protected]", "name": "Work Calendar", "primary": false, "accessRole": "writer"},
{"id": "[email protected]", "name": "Family", "primary": false, "accessRole": "owner"}
]
Use --calendar with any command to specify a different calendar:
# List events from a specific calendar
jean-claude gcal list --calendar [email protected]
# Create event on another calendar
jean-claude gcal create "Team Sync" \
--start "2025-01-15T14:00" --calendar [email protected]
# Search by calendar name (case-insensitive substring match)
jean-claude gcal list --calendar "Family"
The --calendar flag accepts:
primary (default)If a name matches multiple calendars, the command fails with a list of options.
Multiple calendars in one query: The list, search, and invitations
commands accept multiple --calendar flags to query across calendars:
jean-claude gcal list --from 2025-01-15 --to 2025-01-15 \
--calendar "Personal" --calendar "Work"
Each event includes calendar_id and calendar_name in the output.
The status command shows participation metrics:
Max @ Personal (primary) (24 upcoming: 10 yours, 14 invited) [owner]
Roos family (81 upcoming: 3 invited) [owner]
Max @ TGS (44 upcoming, 0 yours) [freeBusyReader]
Check user preferences for which calendars represent their availability vs calendars they just view. When in doubt, ask.
Checking availability: Query multiple calendars at once:
jean-claude gcal list --from 2025-01-07 --to 2025-01-07 \
--calendar "Max @ Personal" --calendar "Roos family"
Creating events: Use the primary calendar unless the user names a different one or context suggests otherwise (work event → work calendar).
When creating events, add useful information proactively:
A calendar invite should have everything attendees need to show up prepared.
Description is visible to all attendees. Never put internal notes or context
about the person/company in the --description field.
Always check the calendar before creating events.
jean-claude gcal list --from 2025-01-21 --to 2025-01-21
If there's a conflict the user may not be aware of, confirm before creating:
Never guess dates. When the user says "Sunday" or "next week", calculate:
date -v+0d "+%A %Y-%m-%d"
Then verify: "Sunday is 2025-12-28 — creating the event for that date."
Never hallucinate emails. If the user says "add Ursula", look up her email or ask. Never invent addresses.
Verify after creating. Run jean-claude gcal list for that date to confirm. If
wrong, delete and recreate before confirming to the user.
Show invite and get confirmation. Before jean-claude gcal create, show
the full invite and ask for approval — just like messages:
Calendar invite to create:
- Title: 1:1: Max & Alice
- When: Tuesday 2025-12-30, 2:00–2:30pm PT
- Attendees: [email protected]
- Location: Zoom (link in description)
- Description: Weekly sync
Create this invite?
Include location and description if set. Wait for "yes" before creating.
Confirm ambiguous locations. "SVB" could mean West Hollywood or Santa Monica — ask which one.
Example workflow:
User: "Add a meeting with Alice for next Tuesday at 2pm"
1. Check: date -v+0d "+%A %Y-%m-%d" → "Friday 2025-12-26"
2. Calculate: next Tuesday = 2025-12-30
3. Look up Alice's email
4. Show the full invite preview (title, date/time, attendees, location, description)
5. Wait for user confirmation
6. Create, then verify with `jean-claude gcal list`
# Today's events
jean-claude gcal list
# Next 7 days
jean-claude gcal list --days 7
# Date range
jean-claude gcal list --from 2025-01-15 --to 2025-01-20
# Simple event
jean-claude gcal create "Team Meeting" \
--start "2025-01-15T14:00" --end "2025-01-15T15:00"
# With attendee, location, and description
jean-claude gcal create "1:1: Max & Alice" \
--start "2025-01-15T10:00" --duration 30 \
--attendees [email protected] \
--location "Conference Room A" \
--description "Weekly sync"
# Multiple attendees
jean-claude gcal create "Team Sync" \
--start "2025-01-15T14:00" --duration 25 \
--attendees "[email protected],[email protected]"
# Event in a specific timezone (use --timezone with the IANA name)
jean-claude gcal create "Call with Denver office" \
--start "2025-01-15T14:00" --duration 60 \
--timezone America/Denver
# All-day event (single day)
jean-claude gcal create "Holiday" \
--start 2025-01-15 --all-day
# Multi-day all-day event
jean-claude gcal create "Vacation" \
--start 2025-01-15 --end 2025-01-20 --all-day
Timezones: Events default to the user's local timezone. When the user
mentions a different timezone (e.g., "3pm Mountain Time"), pass
--timezone America/Denver (or the appropriate IANA name). Use the IANA name,
not a UTC offset — the library handles DST correctly from the name.
# Search (default: 30 days ahead)
jean-claude gcal search "standup"
jean-claude gcal search "standup" --days 90
# Update
jean-claude gcal update EVENT_ID --start "2025-01-16T14:00"
# Delete
jean-claude gcal delete EVENT_ID
List and respond to calendar invitations (events you've been invited to).
Recurring events: The invitations command collapses recurring event instances into a single entry. Each collapsed entry includes:
recurring: true - indicates this is a recurring seriesinstanceCount: N - number of pending instancesid - the parent event ID (use this to respond to all instances at once)Responding to a parent ID accepts/declines all instances in the series. Responding to an instance ID (if you have one) affects only that instance.
# List all pending invitations (no time limit by default)
jean-claude gcal invitations
# Limit to next 7 days
jean-claude gcal invitations --days 7
# Show all individual instances (don't collapse recurring events)
jean-claude gcal invitations --expand
# Accept an invitation (or all instances if recurring)
jean-claude gcal respond EVENT_ID --accept
# Decline an invitation
jean-claude gcal respond EVENT_ID --decline
# Tentatively accept
jean-claude gcal respond EVENT_ID --tentative
# Respond without notifying organizer
jean-claude gcal respond EVENT_ID --accept --no-notify
After responding, archive the invitation email. When the user asked you to RSVP from an invitation email in their inbox, the RSVP makes that email redundant. Archive it as part of the same action — don't leave it for the user to clean up separately:
jean-claude gmail archive THREAD_ID
If the user hasn't mentioned an email (e.g., they asked about an invite from
gcal invitations), skip this — there's no specific thread to archive.
Load these platform-specific guides as needed:
# Messaging
cat ${CLAUDE_PLUGIN_ROOT}/skills/jean-claude/platforms/imessage.md
cat ${CLAUDE_PLUGIN_ROOT}/skills/jean-claude/platforms/whatsapp.md
cat ${CLAUDE_PLUGIN_ROOT}/skills/jean-claude/platforms/signal.md
# Google Workspace (non-Gmail)
cat ${CLAUDE_PLUGIN_ROOT}/skills/jean-claude/platforms/drive.md
cat ${CLAUDE_PLUGIN_ROOT}/skills/jean-claude/platforms/docs.md
cat ${CLAUDE_PLUGIN_ROOT}/skills/jean-claude/platforms/sheets.md
# Apple
cat ${CLAUDE_PLUGIN_ROOT}/skills/jean-claude/platforms/reminders.md
When to load: Load the relevant platform file when the user asks about that service. For example, if they ask "send a WhatsApp message", load whatsapp.md first.
Safety rules still apply: The messaging safety rules in this file (never send without approval, verify recipients) apply to all messaging platforms.
For "near me" queries, use these sources in order:
curl -s ipinfo.io/json | jq '{city, region, country, loc}'
State your assumption: "I see you're in the LA area based on your calendar."
When users correct drafts or behavior, offer to save learnable preferences:
One-off corrections ("make this shorter") are situational, not preferences.
Default behavior: Make the correction, then ask "Want me to remember this?"
If yes, update their personalization skill file (e.g., ~/.claude/skills/managing-messages/SKILL.md).
Auto-learn mode: After a few saved corrections, offer to enable auto-learning. When enabled, save preferences automatically and confirm briefly: "Noted — I'll sign emails 'Best' from now on."
Never auto-learn anything affecting recipients or major workflow changes.
When you hit unexpected exceptions, schema mismatches, or behavior that contradicts documentation, offer to file a GitHub issue.
Don't offer for: authentication failures, permission errors, network issues, or user configuration problems.
I ran into what looks like a bug in jean-claude. Want me to create a GitHub issue? I'll show you the report first and remove any personal information.
See ISSUES.md for formatting and submission.
npx claudepluginhub max-sixty/jean-claude --plugin jean-claudeTriages Gmail inbox by classifying emails using Eisenhower matrix for importance/urgency, determines if replies needed, and drafts responses in user's voice. Useful for inbox zero and email prioritization.
Automates Gmail tasks via Rube MCP (Composio): send/reply emails, search/filter threads, manage labels/drafts/attachments. Requires active Gmail OAuth connection.
Guides Apple Mail inbox triage, organization, replies, and cleanup using MCP tools like get_inbox_overview, move_email, and batch operations for productivity workflows.