Gmail

List inbox (full inbox, grouped by thread)

AIOS_DIR="/Users/nikoatlija/Claude Code/liam_ottley_aios" ~/.venv/bin/python3 ~/.config/gmail/gmail.py list --all

Returns JSON array grouped by thread. Each entry has: id, threadId, from, subject, date, snippet, unread, thread_count. If thread_count > 1, also includes all_ids.

This is the default command. Always use --all unless the user specifically asks for a time-filtered view.

List with time filter

AIOS_DIR="/Users/nikoatlija/Claude Code/liam_ottley_aios" ~/.venv/bin/python3 ~/.config/gmail/gmail.py list --hours 48

Read full email

AIOS_DIR="/Users/nikoatlija/Claude Code/liam_ottley_aios" ~/.venv/bin/python3 ~/.config/gmail/gmail.py read <msg_id>

Move email to label/folder

AIOS_DIR="/Users/nikoatlija/Claude Code/liam_ottley_aios" ~/.venv/bin/python3 ~/.config/gmail/gmail.py move <msg_id> "Label Name"

• If the label doesn't exist, it creates it automatically
• Removes from INBOX, adds to target label, marks as read

List all labels

AIOS_DIR="/Users/nikoatlija/Claude Code/liam_ottley_aios" ~/.venv/bin/python3 ~/.config/gmail/gmail.py labels

Reply to an email

AIOS_DIR="/Users/nikoatlija/Claude Code/liam_ottley_aios" ~/.venv/bin/python3 ~/.config/gmail/gmail.py reply <msg_id> "Your reply body here"

• Automatically threads correctly (In-Reply-To, References headers)
• Prefixes subject with "Re:" if not already there
• Replies to the sender's From/Reply-To address

Reply with attachments

AIOS_DIR="/Users/nikoatlija/Claude Code/liam_ottley_aios" ~/.venv/bin/python3 ~/.config/gmail/gmail.py reply <msg_id> "Your reply body here" --attachments "/path/to/file1.pdf,/path/to/file2.png"

Send a new email

AIOS_DIR="/Users/nikoatlija/Claude Code/liam_ottley_aios" ~/.venv/bin/python3 ~/.config/gmail/gmail.py send "[email protected]" "Subject here" "Body here"

Send with attachments

AIOS_DIR="/Users/nikoatlija/Claude Code/liam_ottley_aios" ~/.venv/bin/python3 ~/.config/gmail/gmail.py send "[email protected]" "Subject" "Body" --attachments "/path/to/file.pdf"

Create a Gmail filter (auto-sort rule)

AIOS_DIR="/Users/nikoatlija/Claude Code/liam_ottley_aios" ~/.venv/bin/python3 ~/.config/gmail/gmail.py filter --from "[email protected]" --label "LabelName" --archive --read

• --from / --to / --subject / --query for criteria
• --label to apply a label, --archive to skip inbox, --read to mark as read, --trash to trash

List existing filters

AIOS_DIR="/Users/nikoatlija/Claude Code/liam_ottley_aios" ~/.venv/bin/python3 ~/.config/gmail/gmail.py filters

Re-authenticate

AIOS_DIR="/Users/nikoatlija/Claude Code/liam_ottley_aios" ~/.venv/bin/python3 ~/.config/gmail/gmail.py auth

Workflow

1. Run list --all to show all inbox emails
2. Display as a table with columns: #, Unread, From, Subject, Replies, Time
3. Ask the user which to move and where
4. Run move for each, confirm results

Display Format

Use a proper markdown table for the inbox:

• Replies column shows thread_count (1 = single message, 2+ = thread)
• Each row is one thread (conversation), not individual messages

Drafting Rules

• Always draft email content and show the user before sending
• Never send without confirmation

One-Time Setup

If credentials.json is missing:

1. Go to Google Cloud Console
2. Create a project (or select existing)
3. Enable the Gmail API (APIs & Services > Library)
4. Go to APIs & Services > Credentials
5. Create an OAuth 2.0 Client ID > Desktop app
6. Download the JSON file
7. Save it to ~/.config/gmail/credentials.json
8. Run the auth command (see above)
9. Browser opens, sign in, authorize, done

Error Handling

• If credentials.json missing, show setup instructions above
• If token.json missing, run auth automatically
• If label not found, the script creates it
• If any command fails, show the error and ask the user what to do