{"id":39492323,"url":"https://github.com/dhellmann/gmail-inbox-summary","last_synced_at":"2026-01-18T05:37:29.766Z","repository":{"id":331685696,"uuid":"1131729511","full_name":"dhellmann/gmail-inbox-summary","owner":"dhellmann","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-11T04:28:10.000Z","size":198,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T05:46:31.836Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dhellmann.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-10T15:31:48.000Z","updated_at":"2026-01-11T04:28:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dhellmann/gmail-inbox-summary","commit_stats":null,"previous_names":["dhellmann/gmail-inbox-summary"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dhellmann/gmail-inbox-summary","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhellmann%2Fgmail-inbox-summary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhellmann%2Fgmail-inbox-summary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhellmann%2Fgmail-inbox-summary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhellmann%2Fgmail-inbox-summary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhellmann","download_url":"https://codeload.github.com/dhellmann/gmail-inbox-summary/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhellmann%2Fgmail-inbox-summary/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28531015,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-18T05:37:29.650Z","updated_at":"2026-01-18T05:37:29.739Z","avatar_url":"https://github.com/dhellmann.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gmail Inbox Summary\n\nA Python application that generates AI-powered summaries of Gmail inbox threads using configurable categorization and Claude Code CLI integration.\n\n\u003e **🔒 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).\n\u003e\n## Features\n\n- **🤖 AI-Powered Summaries**: Uses Claude Code CLI to generate intelligent, context-aware summaries\n- **⚡ Parallel Processing**: Configurable concurrent summarization for 5x faster processing\n- **📧 Gmail Integration**: Secure IMAP access with keychain credential storage for inbox access\n- **⚙️ Configurable Categories**: Define custom thread categories using Gmail labels with pattern matching support\n- **📊 Rich HTML Reports**: Beautiful, responsive HTML output with statistics and collapsible sections\n- **💻 Modern CLI**: Rich command-line interface with progress indicators and colored output\n- **🔧 Flexible Configuration**: YAML configuration files with comprehensive validation\n- **🚀 Smart Caching**: Content-aware caching with automatic change detection for faster subsequent runs\n- **🔒 Secure Credentials**: Cross-platform keychain storage for Gmail passwords with system integration\n- **✅ Configuration Validation**: Automatic validation of config files with clear error messages\n- **🧪 Comprehensive Testing**: Full test coverage with unit and integration tests\n\n## Quick Start\n\n### 1. Installation\n\n```bash\n# Install from PyPI (recommended)\npip install gmail-inbox-summary\n\n# Or install the latest development version from GitHub\npip install git+https://github.com/dhellmann/gmail-inbox-summary.git\n```\n\n### 2. Prerequisites Setup\n\nBefore using the application, you need:\n\n#### Gmail IMAP Access\n\n1. **Enable Gmail IMAP** (if not already enabled):\n   - Go to Gmail Settings → Forwarding and POP/IMAP\n   - Enable IMAP access\n\n2. **Create App-Specific Password** (recommended for security):\n   - Go to your Google Account settings\n   - Navigate to Security → 2-Step Verification → App passwords\n   - Generate a password for \"Mail\"\n\n3. **Store Credentials Securely**:\n\n   ```bash\n   gmail-summary creds store --email your.email@gmail.com\n   ```\n\n   This will prompt for your password and store it securely in your system keychain.\n\n#### Claude Code CLI\n\n1. Install Claude Code CLI: [Installation Instructions](https://claude.ai/code)\n2. Authenticate: `claude auth`\n3. Test connection: `gmail-summary test-claude`\n\n### 3. Configuration\n\nCreate a configuration file using the built-in generator, or manually create one at the default location:\n\n**Quick Start:**\n```bash\ngmail-summary config generate --email your.email@gmail.com\n```\n\n**Manual Configuration:**\nThe configuration file is automatically placed in the platform-specific config directory:\n- **macOS/Linux**: `~/.config/gmail-summary/settings.yml`\n- **Windows**: `%APPDATA%/gmail-summary/settings.yml`\n\nExample configuration:\n\n```yaml\n# Gmail IMAP Configuration\ngmail:\n  email_address: \"your.email@gmail.com\"  # Email stored in keychain\n  imap_server: \"imap.gmail.com\"          # Optional, defaults to imap.gmail.com\n  imap_port: 993                         # Optional, defaults to 993\n\n# Claude Code CLI Configuration\nclaude:\n  cli_path: \"claude\"\n  timeout: 30\n  concurrency: 5  # Number of concurrent summarization tasks (1-20)\n\n# Thread Categories (customize as needed)\n# Categories are now organized by Gmail labels only for simpler and more reliable categorization\ncategories:\n  - name: \"Important Messages\"\n    summary_prompt: \"Summarize this important email, highlighting urgency and required actions.\"\n    criteria:\n      labels:\n        - \"is:important\"  # Gmail's important label\n        - \"is:starred\"    # Starred emails\n\n  - name: \"Meeting Invitations\"\n    summary_prompt: \"Summarize this meeting invitation, including meeting purpose, time, and participants.\"\n    criteria:\n      labels:\n        - \"meeting-invitation\"  # Custom label for meeting invitations\n\n  - name: \"Code\"\n    summary_prompt: \"Summarize this development-related notification, focusing on code changes, PR status, issues, and deployments.\"\n    criteria:\n      labels:\n        - \"github\"      # GitHub notifications\n        - \"gitlab\"      # GitLab notifications\n        - \"gitlab-*\"    # GitLab project-specific labels (pattern matching)\n\n  - name: \"General Email\"\n    summary_prompt: \"Provide a brief, friendly summary of this email.\"\n    criteria: {}  # Empty criteria = catch all remaining emails\n\n# Important Senders (highlighted in reports)\nimportant_senders:\n  - \"boss@company\\\\.com\"\n  - \"urgent@client\\\\.org\"\n\n# Output Configuration\noutput_file: \"inbox_summary.html\"\n# max_threads_per_category: null  # null for unlimited (default), or set a number like 50\n```\n\n### 4. Basic Usage\n\n```bash\n# Generate a configuration file (first time setup)\ngmail-summary config generate --email your.email@gmail.com\n\n# Store credentials securely\ngmail-summary creds store --email your.email@gmail.com\n\n# Test Claude CLI connection\ngmail-summary test-claude\n\n# Generate summary (dry run to test configuration)\ngmail-summary run --dry-run --verbose\n\n# Generate full HTML report\ngmail-summary run --config config.yaml\n\n# Customize output location\ngmail-summary run --output my_summary.html\n\n# Limit threads per category\ngmail-summary run --max-threads 10\n\n# Control parallel processing (faster processing)\ngmail-summary run --concurrency 10\n\n# Combine options for optimal performance\ngmail-summary run --concurrency 8 --max-threads 50 --output daily_report.html\n```\n\n### Credential Management\n\n```bash\n# Store new credentials\ngmail-summary creds store --email your.email@gmail.com\n\n# Update existing credentials\ngmail-summary creds store --email your.email@gmail.com --update\n\n# Check if credentials exist and test IMAP connection\ngmail-summary creds check your.email@gmail.com\n\n# Check with custom config (for non-Gmail IMAP servers)\ngmail-summary creds check your.email@company.com --config config.yaml\n\n# Delete stored credentials\ngmail-summary creds delete your.email@gmail.com\n```\n\n## Configuration Guide\n\n### Gmail Configuration\n\n```yaml\ngmail:\n  email_address: \"your.email@gmail.com\"  # Required: Gmail address (password stored in keychain)\n  imap_server: \"imap.gmail.com\"          # Optional: IMAP server (default: imap.gmail.com)\n  imap_port: 993                         # Optional: IMAP port (default: 993 for SSL)\n\n  # Legacy support (not recommended - use keychain instead)\n  password: \"your-app-password\"          # Will warn users to use keychain storage\n```\n\n**Security Note**: Store passwords in the system keychain using `gmail-summary creds store` instead of putting them in configuration files.\n\n**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.\n\n**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.\n\n### Claude Configuration\n\n```yaml\nclaude:\n  cli_path: \"claude\"        # Path to Claude Code CLI executable\n  timeout: 30              # Timeout in seconds for each summary request\n  concurrency: 5           # Number of concurrent summarization tasks (1-20)\n```\n\n**Performance Configuration**: The `concurrency` setting controls how many email threads are summarized in parallel:\n\n- **Default: 5** - Good balance of speed and resource usage\n- **Range: 1-20** - Configurable based on your system and needs\n- **Higher values** = Faster processing but more system resources\n- **Lower values** = Slower but more conservative resource usage\n\n**Performance Benefits**:\n- **5x faster** with default settings compared to sequential processing\n- **Scalable** up to 20 concurrent tasks for large inboxes\n- **Cache-optimized** for instant retrieval of existing summaries\n\n### Category Configuration\n\nCategories define how threads are organized and summarized. Categories are processed in the order they appear in the configuration file - the first matching category wins.\n\n**Default Behavior**: If no categories are defined in the configuration, a default \"Everything\" category is automatically created that matches all emails.\n\nEach category supports:\n\n```yaml\ncategories:\n  - name: \"Category Name\"           # Display name\n    summary_prompt: \"Custom prompt for this category\"\n    criteria:\n      # Match Gmail labels (only supported criteria type)\n      labels:\n        - \"is:important\"     # Gmail search syntax (recommended)\n        - \"is:starred\"       # Gmail search syntax (recommended)\n        - \"IMPORTANT\"        # Internal label format (also supported)\n        - \"custom-label\"     # Your custom labels\n        - \"project-*\"        # Pattern matching with wildcards\n```\n\n**Label-Only Categorization:**\n\n- **Simplified Configuration**: Categories now only use Gmail labels for more reliable matching\n- **Pattern Support**: Use wildcard patterns like `project-*` to match multiple related labels (e.g., `project-alpha`, `project-beta`)\n- **Gmail Search Syntax**: Use familiar Gmail syntax like `is:important`, `is:starred`, `is:unread`\n- **Custom Labels**: Apply custom labels to emails in Gmail and reference them in your configuration\n- Empty criteria `{}` creates a catch-all category that matches all remaining emails\n\n**Gmail Label Syntax and Pattern Matching:**\n\n- **Gmail Search Syntax**: Use familiar Gmail syntax like `is:important`, `is:starred`, `is:unread`\n- **Custom Labels**: Reference any custom labels you've applied in Gmail (e.g., `project-alpha`, `work-urgent`)\n- **Pattern Matching**: Use wildcard patterns to match multiple related labels:\n  - `gitlab-*` matches `gitlab-project1`, `gitlab-project2`, etc.\n  - `meeting-*` matches `meeting-urgent`, `meeting-weekly`, etc.\n  - Standard Unix filename patterns are supported (`*`, `?`, `[abc]`)\n- **Internal Label Format**: Also supports Gmail's internal format like `IMPORTANT`, `STARRED`, `UNREAD`\n- **Automatic Conversion**: The tool automatically converts Gmail search syntax to internal format\n- **Supported Gmail Search Labels**:\n  - `is:important` → `IMPORTANT`\n  - `is:starred` → `STARRED`\n  - `is:unread` → `UNREAD`\n  - `is:read` → `READ`\n  - `is:sent` → `SENT`\n  - `is:draft` → `DRAFT`\n  - `is:inbox` → `INBOX`\n  - `is:spam` → `SPAM`\n  - `is:trash` → `TRASH`\n  - `is:chat` → `CHAT`\n\n### Advanced Configuration Options\n\n```yaml\n# Highlight important senders\nimportant_senders:\n  - \"ceo@company\\\\.com\"\n  - \"alerts@monitoring\\\\.com\"\n\n# Output settings\noutput_file: \"reports/daily_summary.html\"\nmax_threads_per_category: 50  # Or use null for unlimited processing\n\n# Rate limiting (optional)\ngmail:\n  max_requests_per_minute: 100\n  batch_size: 10\n```\n\n## Command Line Reference\n\n```\nUsage: gmail-summary [OPTIONS] COMMAND [ARGS]...\n\nGenerate AI-powered summaries of Gmail inbox threads.\n\nCommands:\n  config       Manage configuration files.\n  creds        Manage Gmail credentials in keychain.\n  run          Generate AI-powered summaries of Gmail inbox threads.\n  test-claude  Test Claude CLI connection.\n\nMain Command:\n  gmail-summary run [OPTIONS]\n\n  Options:\n    -c, --config PATH       Configuration file path (default: platform-specific)\n    -o, --output PATH       Output HTML file path (overrides config)\n    -n, --max-threads INT  Maximum threads per category (overrides config)\n    -j, --concurrency INT  Number of concurrent summarization tasks (1-20, overrides config)\n    --dry-run              Process threads without generating summaries\n    -v, --verbose          Enable verbose logging\n    --help                 Show this message and exit\n\nTest Command:\n  gmail-summary test-claude [OPTIONS]\n\n  Options:\n    -c, --config PATH      Configuration file path (default: platform-specific)\n    -v, --verbose         Enable verbose logging\n    --help                Show this message and exit\n\nCredential Management:\n  gmail-summary creds store [OPTIONS]\n    -e, --email TEXT       Gmail email address\n    --update              Update existing credentials\n\n  gmail-summary creds check \u003cEMAIL\u003e [OPTIONS]    # Check credentials and test IMAP connection\n    -c, --config PATH      Configuration file (optional, uses Gmail defaults)\n    -v, --verbose         Enable verbose logging\n  gmail-summary creds delete \u003cEMAIL\u003e    # Delete stored credentials\n\nConfiguration Management:\n  gmail-summary config generate [OPTIONS]  # Generate example configuration file\n    -e, --email TEXT       Gmail email address to use in config\n    -o, --output PATH      Configuration file output path (default: platform-specific)\n    -f, --force            Overwrite existing configuration file\n```\n\n## Example Workflows\n\n### Daily Email Summary\n\n```bash\n# Morning routine: generate yesterday's email summary\ngmail-summary run --config daily_config.yaml --output \"summaries/$(date +%Y%m%d).html\"\n```\n\n### Weekly Team Review\n\n```bash\n# Generate summary for team review with more threads and faster processing\ngmail-summary run --max-threads 50 --concurrency 10 --output weekly_team_summary.html\n```\n\n### Performance Optimization\n\n```bash\n# Fast processing for large inboxes\ngmail-summary run --concurrency 15 --max-threads 100\n\n# Conservative processing for limited resources\ngmail-summary run --concurrency 2 --max-threads 20\n\n# Balanced approach for daily use\ngmail-summary run --concurrency 8 --max-threads 50\n```\n\n### Testing New Configuration\n\n```bash\n# Test configuration changes without generating summaries\ngmail-summary run --config new_config.yaml --dry-run --verbose\n```\n\n### First-Time Setup Workflow\n\n```bash\n# 1. Generate configuration file\ngmail-summary config generate --email your.email@gmail.com\n\n# 2. Store credentials securely\ngmail-summary creds store --email your.email@gmail.com\n\n# 3. Test Claude CLI connection\ngmail-summary test-claude\n\n# 4. Test configuration with dry run\ngmail-summary run --dry-run --verbose\n\n# 5. Generate actual summary\ngmail-summary run\n```\n\n## HTML Report Features\n\nThe generated HTML reports include:\n\n- **📊 Statistics Dashboard**: Thread counts, summary success rates, processing time\n- **🗂️ Collapsible Categories**: Organized sections with expand/collapse functionality\n- **⭐ Priority Highlighting**: Important senders marked with visual indicators\n- **📱 Responsive Design**: Mobile-friendly layout that works on all devices\n- **🖨️ Print-Friendly**: Clean formatting when printed or saved as PDF\n- **♿ Accessibility**: Screen reader support and keyboard navigation\n\n## Development\n\n### Project Structure\n\n```\ngmail-inbox-summary/\n├── src/gmail_summarizer/\n│   ├── config.py              # Configuration management\n│   ├── imap_gmail_client.py   # Gmail IMAP integration\n│   ├── credential_manager.py  # Secure keychain credential storage\n│   ├── thread_processor.py    # Thread categorization\n│   ├── llm_summarizer.py      # Claude CLI integration\n│   ├── html_generator.py      # HTML report generation\n│   └── main.py               # CLI interface\n├── templates/\n│   └── summary.html       # Jinja2 HTML template\n├── tests/                 # Comprehensive test suite\n├── config/               # Example configurations\n└── pyproject.toml        # Project configuration\n```\n\n### Running Tests\n\n```bash\n# Run all tests\nhatch run test\n\n# Run with coverage\nhatch run test-cov\n\n# Run specific test file\nhatch run test tests/test_integration.py\n\n# Run linting\nhatch run lint:check\nhatch run lint:fix\n```\n\n### Building and Distribution\n\n```bash\n# Build package for PyPI\nhatch build\n\n# Publish to PyPI (maintainers only)\nhatch publish\n\n# Install in development mode\nhatch run pip install -e .\n\n# Run pre-commit hooks\nhatch run pre-commit run --all-files\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Gmail Authentication Errors:**\n\n```\nError: Gmail credentials not found\n```\n\n- Store credentials: `gmail-summary creds store --email your.email@gmail.com`\n- Ensure Gmail IMAP is enabled in your Gmail settings\n- Use app-specific password, not your regular Gmail password\n- Test stored credentials: `gmail-summary creds check your.email@gmail.com`\n\n**Claude CLI Connection Issues:**\n\n```\nError: Claude CLI not available\n```\n\n- Install Claude Code CLI: [Installation Guide](https://claude.ai/code)\n- Authenticate: `claude auth`\n- Check path: `which claude`\n\n**Configuration Syntax Errors:**\n\n```\nError: Invalid YAML syntax\n```\n\n- Validate YAML syntax with online tools\n- Ensure proper indentation (spaces, not tabs)\n- Check label names and pattern syntax\n\n**Configuration Validation Errors:**\n\n```\nError: Invalid configuration: 1 validation error\n  gmail.email_address\n    Invalid email address format\n```\n\nCommon validation issues:\n- Invalid email format (missing @ symbol)\n- Port numbers outside valid range (1-65535)\n- Timeout values outside valid range (1-600 seconds)\n- Empty category names or prompts\n- Duplicate category names\n- Unknown configuration fields\n\n**No Threads Found:**\n\n```\nWarning: No threads matched any category\n```\n\n- Check Gmail label filters in your configuration\n- Verify that emails have the labels you're looking for\n- Use wildcard patterns like `project-*` to match multiple labels\n- Add a catch-all category with empty criteria: `criteria: {}`\n\n### Debug Mode\n\nEnable detailed logging:\n\n```bash\ngmail-summary run --verbose --config config.yaml --dry-run\n```\n\nThis shows:\n\n- Configuration loading details\n- Thread categorization process\n- Pattern matching results\n- API call information\n\n### Performance Tips\n\n**Parallel Processing**:\n- **Increase concurrency** for faster processing: `--concurrency 10-15` for large inboxes\n- **Default concurrency (5)** works well for most users\n- **Lower concurrency (1-3)** for systems with limited resources or API rate limits\n- **Cache benefits**: Second runs are much faster due to intelligent caching\n\n**Other Optimizations**:\n- Use `max_threads_per_category` to limit processing time (or set to `null` for unlimited processing)\n- Test with `--dry-run` first to verify configuration\n- Consider running during off-peak hours for large inboxes\n- Use specific Gmail labels to pre-filter threads\n- Combine settings: `--concurrency 8 --max-threads 50` for balanced performance\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information on:\n\n- Setting up the development environment\n- Running tests and linters\n- Code style and standards\n- Submitting pull requests\n\nQuick start for contributors:\n\n```bash\ngit clone https://github.com/YOUR-USERNAME/gmail-inbox-summary.git\ncd gmail-inbox-summary\nhatch env create \u0026\u0026 hatch shell\nhatch run pre-commit install\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/dhellmann/gmail-inbox-summary/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/dhellmann/gmail-inbox-summary/discussions)\n- **Documentation**: This README and inline code documentation\n\n---\n\n*Generated with ❤️ using Claude Code CLI*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhellmann%2Fgmail-inbox-summary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhellmann%2Fgmail-inbox-summary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhellmann%2Fgmail-inbox-summary/lists"}