Gmail Inbox Summary

A Python application that generates AI-powered summaries of Gmail inbox threads using configurable categorization and Claude Code CLI integration.

🔒 Security Enhancement: This application uses secure keychain storage for Gmail credentials. Your credentials are protected using your system's native credential manager (macOS Keychain, Windows Credential Manager, or Linux Secret Service).

Features

🤖 AI-Powered Summaries: Uses Claude Code CLI to generate intelligent, context-aware summaries
⚡ Parallel Processing: Configurable concurrent summarization for 5x faster processing
📧 Gmail Integration: Secure IMAP access with keychain credential storage for inbox access
⚙️ Configurable Categories: Define custom thread categories using Gmail labels with pattern matching support
📊 Rich HTML Reports: Beautiful, responsive HTML output with statistics and collapsible sections
💻 Modern CLI: Rich command-line interface with progress indicators and colored output
🔧 Flexible Configuration: YAML configuration files with comprehensive validation
🚀 Smart Caching: Content-aware caching with automatic change detection for faster subsequent runs
🔒 Secure Credentials: Cross-platform keychain storage for Gmail passwords with system integration
✅ Configuration Validation: Automatic validation of config files with clear error messages
🧪 Comprehensive Testing: Full test coverage with unit and integration tests

Quick Start

1. Installation

# Install from PyPI (recommended)
pip install gmail-inbox-summary

# Or install the latest development version from GitHub
pip install git+https://github.com/dhellmann/gmail-inbox-summary.git

2. Prerequisites Setup

Before using the application, you need:

Gmail IMAP Access

Enable Gmail IMAP (if not already enabled):
- Go to Gmail Settings → Forwarding and POP/IMAP
- Enable IMAP access
Create App-Specific Password (recommended for security):
- Go to your Google Account settings
- Navigate to Security → 2-Step Verification → App passwords
- Generate a password for "Mail"
Store Credentials Securely:
```
gmail-summary creds store --email [email protected]
```
This will prompt for your password and store it securely in your system keychain.

Claude Code CLI

Install Claude Code CLI: Installation Instructions
Authenticate: claude auth
Test connection: gmail-summary test-claude

3. Configuration

Create a configuration file using the built-in generator, or manually create one at the default location:

Quick Start:

gmail-summary config generate --email [email protected]

Manual Configuration: The configuration file is automatically placed in the platform-specific config directory:

macOS/Linux: ~/.config/gmail-summary/settings.yml
Windows: %APPDATA%/gmail-summary/settings.yml

Example configuration:

# Gmail IMAP Configuration
gmail:
  email_address: "[email protected]"  # Email stored in keychain
  imap_server: "imap.gmail.com"          # Optional, defaults to imap.gmail.com
  imap_port: 993                         # Optional, defaults to 993

# Claude Code CLI Configuration
claude:
  cli_path: "claude"
  timeout: 30
  concurrency: 5  # Number of concurrent summarization tasks (1-20)

# Thread Categories (customize as needed)
# Categories are now organized by Gmail labels only for simpler and more reliable categorization
categories:
  - name: "Important Messages"
    summary_prompt: "Summarize this important email, highlighting urgency and required actions."
    criteria:
      labels:
        - "is:important"  # Gmail's important label
        - "is:starred"    # Starred emails

  - name: "Meeting Invitations"
    summary_prompt: "Summarize this meeting invitation, including meeting purpose, time, and participants."
    criteria:
      labels:
        - "meeting-invitation"  # Custom label for meeting invitations

  - name: "Code"
    summary_prompt: "Summarize this development-related notification, focusing on code changes, PR status, issues, and deployments."
    criteria:
      labels:
        - "github"      # GitHub notifications
        - "gitlab"      # GitLab notifications
        - "gitlab-*"    # GitLab project-specific labels (pattern matching)

  - name: "General Email"
    summary_prompt: "Provide a brief, friendly summary of this email."
    criteria: {}  # Empty criteria = catch all remaining emails

# Important Senders (highlighted in reports)
important_senders:
  - "boss@company\\.com"
  - "urgent@client\\.org"

# Output Configuration
output_file: "inbox_summary.html"
# max_threads_per_category: null  # null for unlimited (default), or set a number like 50

4. Basic Usage

# Generate a configuration file (first time setup)
gmail-summary config generate --email [email protected]

# Store credentials securely
gmail-summary creds store --email [email protected]

# Test Claude CLI connection
gmail-summary test-claude

# Generate summary (dry run to test configuration)
gmail-summary run --dry-run --verbose

# Generate full HTML report
gmail-summary run --config config.yaml

# Customize output location
gmail-summary run --output my_summary.html

# Limit threads per category
gmail-summary run --max-threads 10

# Control parallel processing (faster processing)
gmail-summary run --concurrency 10

# Combine options for optimal performance
gmail-summary run --concurrency 8 --max-threads 50 --output daily_report.html

Credential Management

# Store new credentials
gmail-summary creds store --email [email protected]

# Update existing credentials
gmail-summary creds store --email [email protected] --update

# Check if credentials exist and test IMAP connection
gmail-summary creds check [email protected]

# Check with custom config (for non-Gmail IMAP servers)
gmail-summary creds check [email protected] --config config.yaml

# Delete stored credentials
gmail-summary creds delete [email protected]

Configuration Guide

Gmail Configuration

gmail:
  email_address: "[email protected]"  # Required: Gmail address (password stored in keychain)
  imap_server: "imap.gmail.com"          # Optional: IMAP server (default: imap.gmail.com)
  imap_port: 993                         # Optional: IMAP port (default: 993 for SSL)

  # Legacy support (not recommended - use keychain instead)
  password: "your-app-password"          # Will warn users to use keychain storage

Security Note: Store passwords in the system keychain using gmail-summary creds store instead of putting them in configuration files.

Convenience Feature: The creds check command can work without a configuration file for Gmail accounts, using default IMAP settings (imap.gmail.com:993). For custom IMAP servers, provide a configuration file with the --config option.

Configuration Validation: All configuration files are automatically validated using Pydantic models. Invalid configurations will show clear error messages with specific validation failures, including invalid email formats, out-of-range values, and unknown fields.

Claude Configuration

claude:
  cli_path: "claude"        # Path to Claude Code CLI executable
  timeout: 30              # Timeout in seconds for each summary request
  concurrency: 5           # Number of concurrent summarization tasks (1-20)

Performance Configuration: The concurrency setting controls how many email threads are summarized in parallel:

Default: 5 - Good balance of speed and resource usage
Range: 1-20 - Configurable based on your system and needs
Higher values = Faster processing but more system resources
Lower values = Slower but more conservative resource usage

Performance Benefits:

5x faster with default settings compared to sequential processing
Scalable up to 20 concurrent tasks for large inboxes
Cache-optimized for instant retrieval of existing summaries

Category Configuration

Categories define how threads are organized and summarized. Categories are processed in the order they appear in the configuration file - the first matching category wins.

Default Behavior: If no categories are defined in the configuration, a default "Everything" category is automatically created that matches all emails.

Each category supports:

categories:
  - name: "Category Name"           # Display name
    summary_prompt: "Custom prompt for this category"
    criteria:
      # Match Gmail labels (only supported criteria type)
      labels:
        - "is:important"     # Gmail search syntax (recommended)
        - "is:starred"       # Gmail search syntax (recommended)
        - "IMPORTANT"        # Internal label format (also supported)
        - "custom-label"     # Your custom labels
        - "project-*"        # Pattern matching with wildcards

Label-Only Categorization:

Simplified Configuration: Categories now only use Gmail labels for more reliable matching
Pattern Support: Use wildcard patterns like project-* to match multiple related labels (e.g., project-alpha, project-beta)
Gmail Search Syntax: Use familiar Gmail syntax like is:important, is:starred, is:unread
Custom Labels: Apply custom labels to emails in Gmail and reference them in your configuration
Empty criteria {} creates a catch-all category that matches all remaining emails

Gmail Label Syntax and Pattern Matching:

Gmail Search Syntax: Use familiar Gmail syntax like is:important, is:starred, is:unread
Custom Labels: Reference any custom labels you've applied in Gmail (e.g., project-alpha, work-urgent)
Pattern Matching: Use wildcard patterns to match multiple related labels:
- gitlab-* matches gitlab-project1, gitlab-project2, etc.
- meeting-* matches meeting-urgent, meeting-weekly, etc.
- Standard Unix filename patterns are supported (*, ?, [abc])
Internal Label Format: Also supports Gmail's internal format like IMPORTANT, STARRED, UNREAD
Automatic Conversion: The tool automatically converts Gmail search syntax to internal format
Supported Gmail Search Labels:
- is:important → IMPORTANT
- is:starred → STARRED
- is:unread → UNREAD
- is:read → READ
- is:sent → SENT
- is:draft → DRAFT
- is:inbox → INBOX
- is:spam → SPAM
- is:trash → TRASH
- is:chat → CHAT

Advanced Configuration Options

# Highlight important senders
important_senders:
  - "ceo@company\\.com"
  - "alerts@monitoring\\.com"

# Output settings
output_file: "reports/daily_summary.html"
max_threads_per_category: 50  # Or use null for unlimited processing

# Rate limiting (optional)
gmail:
  max_requests_per_minute: 100
  batch_size: 10

Command Line Reference

Usage: gmail-summary [OPTIONS] COMMAND [ARGS]...

Generate AI-powered summaries of Gmail inbox threads.

Commands:
  config       Manage configuration files.
  creds        Manage Gmail credentials in keychain.
  run          Generate AI-powered summaries of Gmail inbox threads.
  test-claude  Test Claude CLI connection.

Main Command:
  gmail-summary run [OPTIONS]

  Options:
    -c, --config PATH       Configuration file path (default: platform-specific)
    -o, --output PATH       Output HTML file path (overrides config)
    -n, --max-threads INT  Maximum threads per category (overrides config)
    -j, --concurrency INT  Number of concurrent summarization tasks (1-20, overrides config)
    --dry-run              Process threads without generating summaries
    -v, --verbose          Enable verbose logging
    --help                 Show this message and exit

Test Command:
  gmail-summary test-claude [OPTIONS]

  Options:
    -c, --config PATH      Configuration file path (default: platform-specific)
    -v, --verbose         Enable verbose logging
    --help                Show this message and exit

Credential Management:
  gmail-summary creds store [OPTIONS]
    -e, --email TEXT       Gmail email address
    --update              Update existing credentials

  gmail-summary creds check <EMAIL> [OPTIONS]    # Check credentials and test IMAP connection
    -c, --config PATH      Configuration file (optional, uses Gmail defaults)
    -v, --verbose         Enable verbose logging
  gmail-summary creds delete <EMAIL>    # Delete stored credentials

Configuration Management:
  gmail-summary config generate [OPTIONS]  # Generate example configuration file
    -e, --email TEXT       Gmail email address to use in config
    -o, --output PATH      Configuration file output path (default: platform-specific)
    -f, --force            Overwrite existing configuration file

Example Workflows

Daily Email Summary

# Morning routine: generate yesterday's email summary
gmail-summary run --config daily_config.yaml --output "summaries/$(date +%Y%m%d).html"

Weekly Team Review

# Generate summary for team review with more threads and faster processing
gmail-summary run --max-threads 50 --concurrency 10 --output weekly_team_summary.html

Performance Optimization

# Fast processing for large inboxes
gmail-summary run --concurrency 15 --max-threads 100

# Conservative processing for limited resources
gmail-summary run --concurrency 2 --max-threads 20

# Balanced approach for daily use
gmail-summary run --concurrency 8 --max-threads 50

Testing New Configuration

# Test configuration changes without generating summaries
gmail-summary run --config new_config.yaml --dry-run --verbose

First-Time Setup Workflow

# 1. Generate configuration file
gmail-summary config generate --email [email protected]

# 2. Store credentials securely
gmail-summary creds store --email [email protected]

# 3. Test Claude CLI connection
gmail-summary test-claude

# 4. Test configuration with dry run
gmail-summary run --dry-run --verbose

# 5. Generate actual summary
gmail-summary run

HTML Report Features

The generated HTML reports include:

📊 Statistics Dashboard: Thread counts, summary success rates, processing time
🗂️ Collapsible Categories: Organized sections with expand/collapse functionality
⭐ Priority Highlighting: Important senders marked with visual indicators
📱 Responsive Design: Mobile-friendly layout that works on all devices
🖨️ Print-Friendly: Clean formatting when printed or saved as PDF
♿ Accessibility: Screen reader support and keyboard navigation

Development

Project Structure

gmail-inbox-summary/
├── src/gmail_summarizer/
│   ├── config.py              # Configuration management
│   ├── imap_gmail_client.py   # Gmail IMAP integration
│   ├── credential_manager.py  # Secure keychain credential storage
│   ├── thread_processor.py    # Thread categorization
│   ├── llm_summarizer.py      # Claude CLI integration
│   ├── html_generator.py      # HTML report generation
│   └── main.py               # CLI interface
├── templates/
│   └── summary.html       # Jinja2 HTML template
├── tests/                 # Comprehensive test suite
├── config/               # Example configurations
└── pyproject.toml        # Project configuration

Running Tests

# Run all tests
hatch run test

# Run with coverage
hatch run test-cov

# Run specific test file
hatch run test tests/test_integration.py

# Run linting
hatch run lint:check
hatch run lint:fix

Building and Distribution

# Build package for PyPI
hatch build

# Publish to PyPI (maintainers only)
hatch publish

# Install in development mode
hatch run pip install -e .

# Run pre-commit hooks
hatch run pre-commit run --all-files

Troubleshooting

Common Issues

Gmail Authentication Errors:

Error: Gmail credentials not found

Store credentials: gmail-summary creds store --email [email protected]
Ensure Gmail IMAP is enabled in your Gmail settings
Use app-specific password, not your regular Gmail password
Test stored credentials: gmail-summary creds check [email protected]

Claude CLI Connection Issues:

Error: Claude CLI not available

Install Claude Code CLI: Installation Guide
Authenticate: claude auth
Check path: which claude

Configuration Syntax Errors:

Error: Invalid YAML syntax

Validate YAML syntax with online tools
Ensure proper indentation (spaces, not tabs)
Check label names and pattern syntax

Configuration Validation Errors:

Error: Invalid configuration: 1 validation error
  gmail.email_address
    Invalid email address format

Common validation issues:

Invalid email format (missing @ symbol)
Port numbers outside valid range (1-65535)
Timeout values outside valid range (1-600 seconds)
Empty category names or prompts
Duplicate category names
Unknown configuration fields

No Threads Found:

Warning: No threads matched any category

Check Gmail label filters in your configuration
Verify that emails have the labels you're looking for
Use wildcard patterns like project-* to match multiple labels
Add a catch-all category with empty criteria: criteria: {}

Debug Mode

Enable detailed logging:

gmail-summary run --verbose --config config.yaml --dry-run

This shows:

Configuration loading details
Thread categorization process
Pattern matching results
API call information

Performance Tips

Parallel Processing:

Increase concurrency for faster processing: --concurrency 10-15 for large inboxes
Default concurrency (5) works well for most users
Lower concurrency (1-3) for systems with limited resources or API rate limits
Cache benefits: Second runs are much faster due to intelligent caching

Other Optimizations:

Use max_threads_per_category to limit processing time (or set to null for unlimited processing)
Test with --dry-run first to verify configuration
Consider running during off-peak hours for large inboxes
Use specific Gmail labels to pre-filter threads
Combine settings: --concurrency 8 --max-threads 50 for balanced performance

Contributing

We welcome contributions! Please see our Contributing Guide for detailed information on:

Setting up the development environment
Running tests and linters
Code style and standards
Submitting pull requests

Quick start for contributors:

git clone https://github.com/YOUR-USERNAME/gmail-inbox-summary.git
cd gmail-inbox-summary
hatch env create && hatch shell
hatch run pre-commit install

License

MIT License - see LICENSE file for details.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: This README and inline code documentation

Generated with ❤️ using Claude Code CLI

Name		Name	Last commit message	Last commit date
Latest commit History 57 Commits
src/gmail_summarizer		src/gmail_summarizer
templates		templates
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
INSTALL.md		INSTALL.md
README.md		README.md
plan.md		plan.md
pyproject.toml		pyproject.toml

dhellmann/gmail-inbox-summary

Folders and files

Latest commit

History

Repository files navigation

Gmail Inbox Summary

Features

Quick Start

1. Installation

2. Prerequisites Setup

Gmail IMAP Access

Claude Code CLI

3. Configuration

4. Basic Usage

Credential Management

Configuration Guide

Gmail Configuration

Claude Configuration

Category Configuration

Advanced Configuration Options

Command Line Reference

Example Workflows

Daily Email Summary

Weekly Team Review

Performance Optimization

Testing New Configuration

First-Time Setup Workflow

HTML Report Features

Development

Project Structure

Running Tests

Building and Distribution

Troubleshooting

Common Issues

Debug Mode

Performance Tips

Contributing

License

Support

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages