GitHub Notifications Copilot

🤖 Intelligent GitHub notification triage system powered by Claude AI

Automatic classification, prioritization, and action on your GitHub notifications with P1/P2/P3 levels, smart muting, and a feedback loop for continuous improvement.

🎯 Why You Need This

With 314+ unread notifications spread across multiple repos, manual triage is impossible. This system:

• Classifies each notification: P1 (urgent), P2 (important), P3 (low)
• Suggests actions: review, approve, investigate, mute, skip
• Auto-executes: mutes low-priority items, labels dependencies
• Learns: tracks your feedback to improve classifications over time
• Scales: processes hundreds of notifications in minutes

🚀 Quick Start (5 minutes)

1. Clone & Install

git clone https://github.com/labgadget015-dotcom/github-notifications-copilot.git
cd github-notifications-copilot
pip install -r requirements.txt

2. Set Environment Variables

export GITHUB_TOKEN="ghp_your_github_token_here"
export ANTHROPIC_API_KEY="sk-ant-your_key_here"

3. Run the Triage

python notification_copilot.py --dry-run

This shows what would happen without making actual changes.

4. Execute (When Ready)

python notification_copilot.py --execute

📋 How It Works

┌─────────────────────────────────────────────────────────────┐
│ GitHub Notifications API                                     │
│ (314 unread items)                                          │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ Enrich & Normalize                                          │
│ Extract: repo, type, title, reason, timestamp              │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ LLM Classifier (Claude)                                     │
│ ┌──────────────────────────────────────────────────────┐   │
│ │ P1: Security, urgent reviews, production bugs        │   │
│ │ P2: Important features, workflow failures            │   │
│ │ P3: Dependencies, discussions, old threads           │   │
│ └──────────────────────────────────────────────────────┘   │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ Actions Executor                                            │
│ • Auto-mute P3 from non-critical repos                     │
│ • Auto-label dependencies                                  │
│ • Save state to JSON for dashboard                         │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ Output                                                      │
│ • digest.md (human-readable summary)                       │
│ • notifications_state.json (machine-readable)              │
│ • dashboard UI (coming soon)                               │
└─────────────────────────────────────────────────────────────┘

📁 Project Structure

github-notifications-copilot/
├── notification_copilot.py        # Main entry point & orchestration
├── github_api_client.py           # GitHub API wrapper
├── llm_classifier.py              # LLM-powered triage logic
├── actions_executor.py            # Auto-label, mute, archive
├── config.yaml                    # Configuration (repos, labels, etc.)
├── requirements.txt               # Python dependencies
├── README.md                      # This file
└── examples/
    ├── sample_notifications.json  # Test data
    └── sample_output.json         # Example triage output

🔧 Configuration (config.yaml)

github:
  api_url: https://api.github.com

llm:
  provider: anthropic
  model: claude-3-5-sonnet-20241022

triage:
  confidence_threshold: 0.7
  important_repos:
    - labgadget015-dotcom/autonomous-github-agent
    - labgadget015-dotcom/analysis-os
    - labgadget015-dotcom/github-multi-agent-system
  mute_labels:
    - dependencies
    - chore
    - stale

actions:
  auto_mute: true
  auto_label: true
  dry_run: true  # Set to false to actually execute

📊 Triage Categories

P1 (Act Within 1 Hour)

• Your PRs waiting on you
• Security/vulnerability issues
• Production-critical bugs assigned to you
• Code reviews you requested
• Blocked PRs (branch protection)

P2 (Handle Today)

• Your open PRs or issues needing review
• Important bugs affecting core repos
• Workflow failures in repos you own
• Feature requests for active projects

P3 (Handle When Ready)

• Dependencies/dependabot updates
• CI passes/routine status checks
• Discussions/comments on issues
• Old threads (>2 days with no action)
• Chores/documentation

💾 Output Files

notifications_state.json

Machine-readable state of all notifications:

{
  "fetched_at": "2026-01-24T03:00:00Z",
  "total": 314,
  "by_priority": { "P1": 12, "P2": 45, "P3": 257 },
  "notifications": [
    {
      "notification": { ... },
      "triage": {
        "priority": "P1",
        "category": "security",
        "action": "review_now",
        "confidence": 0.95,
        "reasoning": "Security issue assigned to you"
      }
    }
  ]
}

digest.md

Human-readable summary:

# GitHub Notifications Digest
Generated: 2026-01-24T03:00:00Z

## Summary
- **P1 (Urgent)**: 12 items
- **P2 (Important)**: 45 items
- **P3 (Low)**: 257 items

## P1 Items (Act Now)
- **autonomous-github-agent**: Security issue in OAuth flow
  - Action: review_now | Confidence: 95%
- **analysis-os**: Workflow failed - Quality Check
  - Action: investigate | Confidence: 88%

🔄 Feedback Loop

Improve triage accuracy by rating classifications:

1. Run triage: python notification_copilot.py
2. Review output in digest.md
3. Rate accuracy: "Was P1 correct? P2? P3?"
4. Save feedback to feedback.json
5. Script auto-adjusts LLM prompt based on patterns

Example feedback:

{
  "notification_id": "123456",
  "original_priority": "P2",
  "user_priority": "P1",
  "notes": "This PR blocks other work, should be P1"
}

🎮 Usage Patterns

Pattern 1: Daily Ritual (Morning)

# 1. Fetch & triage
python notification_copilot.py --output digest.md

# 2. Read digest
cat digest.md

# 3. Handle P1 items (5-10 min)
# Go to GitHub, review P1 items

# 4. Execute auto-mutes
python notification_copilot.py --execute --mute-p3

Pattern 2: Scheduled (Every 2 Hours)

Use cron or GitHub Actions:

# In your crontab
0 */2 * * * cd /path/to/copilot && python notification_copilot.py --auto-execute >> copilot.log 2>&1

Pattern 3: Interactive (Custom Actions)

from notification_copilot import NotificationCopilot

copilot = NotificationCopilot()
notifications = copilot.fetch()
triaged = copilot.classify(notifications)

# Custom logic
for item in triaged:
    if item['triage']['priority'] == 'P1':
        # Do something special
        pass

📈 Metrics to Track

• P1 response time: How fast you handle urgent items
• False positive rate: P3 items you actually care about
• Mute accuracy: Items you muted but later needed
• Time saved: Minutes spent on triage vs. manual sorting

🛠 Advanced: Custom Triage Rules

Edit llm_classifier.py to add repo-specific logic:

if repo == "critical-production-repo":
    # All failures -> P1
    return {"priority": "P1", ...}

if "security" in title.lower():
    # Always P1
    return {"priority": "P1", ...}

🚀 Roadmap

• Web dashboard (React)
• Slack/email digest integration
• GitHub Actions workflow
• Custom label-based triage rules
• Team-based notification grouping
• Webhook for real-time processing
• Metrics dashboard

💡 Pro Tips

1. Start with dry-run: Always use --dry-run first to see what would happen
2. Customize repos: Update important_repos list to match your workflow
3. Review mute labels: Add labels that are noise for you
4. Batch processing: Run at consistent times (morning, afternoon, evening)
5. Archive old: Use GitHub's archive feature for threads >1 month old

🤝 Contributing

Fork, improve, and submit PRs! Ideas:

• Better triage prompts
• Additional LLM providers (OpenAI, Anthropic alternatives)
• Dashboard UI
• Integration with project management tools

📄 License

MIT

👤 About

Built for autonomous development workflows. Designed to eliminate notification fatigue and let you focus on high-value work.

---

Questions? Open an issue or reach out.

Built with: Python 3.9+, Claude API, GitHub API, asyncio