⚡ IssuePilot: Custom Open-Source Issue Digest & Alert Agent

IssuePilot is a zero-database, highly customizable open-source issue discovery engine. It continuously searches, evaluates, and delivers fresh, beginner-friendly GitHub issues tailored specifically to your custom tech stack directly to your Telegram, Discord, or Console.

---

✨ Why IssuePilot?

• ⚡ Zero Database Required: 100% lightweight state-free execution. No MongoDB or SQL database setup needed!
• 🕒 Time-Window Duplicate Prevention: Queries issues created within a date window (created:>={YYYY-MM-DD}), preventing duplicate alerts without storing state.
• 🎯 Custom Tech Stack Configuration: Simply type your favorite technologies into config.yaml (python, django, react, rust, golang, flutter, docker, etc.).
• 🌐 Global GitHub Search: Automatically searches across all 100+ million open-source public repos on GitHub for unassigned issues.
• 🔄 Fresh Issue Search: Queries open GitHub issues sorted by creation date descending (sort="created", direction="desc") so you get active, recent tasks.
• 📱 Multi-Channel Alerts: Supports Telegram Bot, Discord Webhooks, or Console Output.
• ☁️ 1-Click 2-Minute Setup: Fork the repo, add your Telegram/Discord credentials to GitHub Secrets, and enjoy daily issue alerts automatically for free!

---

🛠️ How It Works

┌───────────────────────────┐
│     1. User Config        │ ➔ User defines tech_stack, date window & notification channel in config.yaml
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│     2. GitHub Scraper     │ ➔ Pulls fresh issues matching created:>={YYYY-MM-DD} across all repos
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│    3. Dynamic Evaluator   │ ➔ Scores 1-100 & reranks issues against user's custom stack
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│   4. Daily Dispatcher     │ ➔ Delivers top 3 custom issues straight to Telegram/Discord
└───────────────────────────┘

---

📊 Dynamic 100-Point Scoring Matrix

Criteria	Weight	Description
Custom Stack Match	40%	Dynamically awards points based on exact matches against the user's config.yaml tech stack array.
Issue Clarity	30%	Evaluates description length ($>300/600$ chars) and presence of structural indicators (steps to reproduce, code blocks).
Setup & Beginner Labels	20%	Filters for good first issue, easy, beginner friendly labels and setup keywords (docker, contributing).
Discussion Activity	10%	Evaluates maintainer responsiveness and open comment count ($0 < \text{comments} \le 5$).

---

⚙️ Quick Start (2-Minute Setup)

1. Clone & Install Dependencies

git clone https://github.com/xlord101/open-source-contribution-agent.git
cd open-source-contribution-agent
pip install -r requirements.txt

2. Customize config.yaml

Edit config.yaml to specify your preferred tech stack and delivery channel:

# Add your favorite tech stacks!
tech_stack:
  - "python"
  - "django"
  - "react"
  - "typescript"
  - "fastapi"

# Time-window date filter (Prevents duplicate alerts!)
created_within_days: 30
difficulty_preference: "beginner"

# Target specific repos or leave [] to search all of GitHub
target_repos: []

# Options: "telegram", "discord", or "console"
notification_channel: "telegram"

3. Run Locally

python main.py

---

☁️ Automated GitHub Actions Setup (Zero Cost)

1. Fork this repository: https://github.com/xlord101/open-source-contribution-agent.
2. Go to Settings ➔ Secrets and variables ➔ Actions.
3. Add your secrets:
   • TELEGRAM_BOT_TOKEN (from @BotFather)
   • TELEGRAM_CHAT_ID (from @userinfobot)
   • DISCORD_WEBHOOK_URL (Optional for Discord)

The GitHub Actions workflow will run automatically every day at 06:00 UTC and deliver fresh issues tailored to your tech stack straight to your phone!

---

❓ Frequently Asked Questions (FAQ)

How does IssuePilot prevent duplicate alerts without a database?

IssuePilot uses Time-Window Date Filtering (created:>={YYYY-MM-DD}). Every morning, it searches only for open issues created within your configured date window (e.g. last 14 or 30 days) and sorts them descending.

Can I monitor specific GitHub repositories instead of all of GitHub?

Yes! Simply list your target repositories in config.yaml:

target_repos:
  - "fastapi/fastapi"
  - "facebook/react"

Does IssuePilot require an OpenAI or Gemini API Key?

No! IssuePilot uses a zero-cost, zero-latency dynamic scoring engine that matches issues against your tech stack array without requiring any paid LLM API keys.

---

📜 License

Distributed under the MIT License. See LICENSE for more information.