Gmail Organizer

Base directory for this skill: {see the "Base directory" header above}

IMPORTANT: All script paths in this skill are relative to the base directory provided in the skill invocation header. When running scripts, use the full path constructed from that base directory. For example, if the base directory is /path/to/skills/gmail-organizer, run scripts as bash /path/to/skills/gmail-organizer/scripts/gmail-analyze.sh.

Gmail Organizer

Organize, analyze, and clean up Gmail inboxes using the gog CLI tool (gogcli). Designed for large inboxes (10k+ messages) with a safety-first approach that requires explicit user permission for any destructive action.

Prerequisites

• GOG CLI (gog) — installed and authenticated. Install from github.com/slstracker/gogcli. Verify with: gog gmail labels list
• jq installed for JSON processing
• GOG_ACCOUNT environment variable set, or pass --account to scripts

Safety Rules — MANDATORY, NEVER BYPASS

These rules are non-negotiable. They are enforced at the script level AND must be followed in the workflow:

1. DELETING any messages — REQUIRES showing preview + count to user AND getting explicit "yes" in chat
2. MARKING messages as read — REQUIRES showing preview + count to user AND getting explicit "yes" in chat
3. Archiving messages (removing INBOX label) — REQUIRES showing preview + count to user AND getting explicit "yes" in chat
4. Always run gmail-safe-batch.sh in preview mode first (no --execute flag)
5. Only pass --execute AFTER the user has seen the preview and explicitly confirmed
6. Process in batches of 100 message IDs max per API call
7. Never use --force flag with gog commands to skip confirmations

Core Workflow

Phase 1: Analyze Inbox

Run the analysis script to understand inbox composition:

bash <base-dir>/scripts/gmail-analyze.sh

This produces a report with:

• Label statistics with message counts
• Gmail category breakdown (promotions, social, updates, forums)
• Age distribution of messages
• Top senders by volume (from recent 90-day sample)
• Top sender domains
• Newsletter detection (emails with unsubscribe headers)
• Unread and large message counts

Present the analysis as a clear, organized summary. Identify the biggest opportunities for cleanup and organization.

Phase 2: Propose Organization Strategy

Based on the analysis, propose:

1. Label taxonomy — hierarchical labels matching the user's email patterns. Common structures:

   • Auto/<service> for automated notifications
   • News/<type> for newsletters and marketing
   • Finance/<type> for receipts and invoices
   • Social/<platform> for social media notifications

2. Filter rules — for high-volume recurring senders to auto-label future mail

3. Cleanup targets — categories safe to bulk-archive or delete (e.g., old promotions, expired notifications)

Wait for user approval before proceeding. Adjust the plan based on feedback.

Phase 3: Create Labels

Create the approved label structure:

gog gmail labels create "Parent/Child"

Phase 4: Create Filters

For each recurring pattern, create a Gmail filter:

gog gmail filters create --from '[email protected]' --add-label 'Auto/Service'

List existing filters first to avoid duplicates:

gog gmail filters list --json

Phase 5: Batch Organize Existing Messages

Use the safe batch script for ALL batch operations. Always preview first:

# Step 1: Preview (ALWAYS do this first)
bash <base-dir>/scripts/gmail-safe-batch.sh label "from:[email protected]" "Auto/GitHub"

# Step 2: Show preview to user, ask for confirmation

# Step 3: Execute ONLY after user confirms
bash <base-dir>/scripts/gmail-safe-batch.sh label "from:[email protected]" "Auto/GitHub" --execute

Phase 6: Cleanup (Permission Required)

For destructive operations, strictly follow this protocol:

1. Run preview: bash <base-dir>/scripts/gmail-safe-batch.sh delete "<query>"
2. Present the preview to the user (sample subjects + sender + total count)
3. Ask: "This will delete N messages matching ''. Here are 5 examples: [list]. Proceed? (yes/no)"
4. ONLY if user says yes: run with --execute

Same protocol for mark-read and archive actions.

Script Reference

gmail-analyze.sh

Full inbox analysis. All operations are read-only.

Usage: bash <base-dir>/scripts/gmail-analyze.sh [--account email] [--max-sample N] [--section SECTION]

Sections: labels, categories, age, senders, domains, newsletters, unread, large, all (default)

gmail-safe-batch.sh

Safety-wrapped batch operations. Preview-by-default, requires --execute for actual changes.

Usage: bash <base-dir>/scripts/gmail-safe-batch.sh <action> <gmail-query> [label] [--execute] [--max N] [--account email]

Actions:
  label      — Add a label to matching messages (requires label arg)
  unlabel    — Remove a label from matching messages (requires label arg)
  archive    — Remove INBOX label (requires user permission)
  mark-read  — Remove UNREAD label (requires user permission)
  delete     — Delete messages (requires user permission)

Without --execute: shows 5 sample messages and total count estimate. With --execute: performs the operation in batches of 100.

Useful gog Commands Quick Reference

# Search messages
gog gmail messages search '<query>' --max N --json

# Get thread detail
gog gmail thread get <threadId> --json

# Label management
gog gmail labels list --json
gog gmail labels get <label> --json
gog gmail labels create "Name"

# Filter management
gog gmail filters list --json
gog gmail filters create --from '<email>' --add-label '<label>'

# Batch operations
gog gmail batch modify <id>... --add <label> --remove <label>
gog gmail batch delete <id>...

Gmail Search Query Syntax

Common operators for targeting messages:

• from:[email protected] — by sender
• to:[email protected] — by recipient
• subject:keyword — in subject
• newer_than:7d / older_than:1y — by age
• is:unread / is:read — by read status
• has:attachment / larger:5m — by size/attachment
• category:promotions — Gmail categories
• label:INBOX — by label
• {from:[email protected] from:[email protected]} — OR grouping

Additional Resources

Reference Files

• references/gogcli-gmail-reference.md — Complete gog gmail command reference with all subcommands, flags, and output formats
• references/organization-patterns.md — Email organization strategies, label taxonomies, filter patterns, and cleanup playbooks for different inbox types