🔥 GitHub Trending Agent v2.2

Smart agent for discovering, analyzing, cloning, and RUNNING trending GitHub repositories.

No more auto-downloading everything! Clone → Run → Preview in seconds.

✨ Features

Feature	Description
🔍 GitHub-Like Filters	Language, date range, spoken language, stars, topics
🧠 Smart Filtering	Skips enterprise updates, focuses on interesting projects
📝 AI Summaries	Ollama-powered explanations (with rule-based fallback)
🎯 Interest Scoring	Repos ranked by relevance to your preferences
🚀 Auto-Run & Preview	Clone → Install → Run → Get preview URL
🔧 Dependency Check	Detect missing Go/Node/Python/Docker with install commands
🌐 Dual UI System	Developer UI + Agent UI (for Ollama)
📦 CLI Skills	Python scripts callable by Claude or other agents
🔌 MCP Server	Claude Desktop integration with 10 tools
🔗 REST API	Integrate with n8n, Telegram, or any automation tool

---

🚀 Quick Start

1. Start the Server

# One-click
start.bat

# Or manual
cd C:\github-trending-agent\api
pip install -r requirements.txt
python main.py

2. Open the Dashboard

UI	URL	Purpose
API Docs	http://localhost:8000/docs	Swagger docs
Dashboard	Run separately: cd dashboard && npm run dev	Modern Vite + Tailwind UI

---

🚀 Auto-Run & Preview (NEW!)

Clone a repo and start it with one command:

# Clone first
python skills/clone_repo.py langchain-ai/langchain

# Run it (auto-detects, installs, starts server)
python skills/run_repo.py langchain-ai/langchain

# Output:
# ✅ Project is running!
#    📍 Preview URL: http://localhost:3000

Supported: Node.js, Python (FastAPI/Flask/Streamlit/Gradio), Docker, Go, Rust

---

🔧 Dependency Check (NEW!)

# Check all dependencies
python skills/check_deps.py

# Check for specific project type
python skills/check_deps.py --for go

# Get install command
python skills/check_deps.py --install go
# Output: winget install GoLang.Go

See Dependencies Documentation for full documentation.

---

🔍 GitHub-Like Filters

Filter	API Param	CLI Flag
Language	?language=python	--language python
Time Range	?since=weekly	--since weekly
Min Stars	?min_stars=100	--min-stars 100
Topic	?topic=llm	--topic llm

---

📦 CLI Skills

# Fetch trending
python skills/fetch_trending.py --language python --format summary

# Analyze a repo
python skills/analyze_repo.py owner/repo --format markdown

# Clone a repo
python skills/clone_repo.py owner/repo

# Run a repo
python skills/run_repo.py owner/repo

# Check dependencies
python skills/check_deps.py --for nodejs

---

🔌 MCP Server (Claude Desktop)

Setup

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "github-trending": {
      "command": "python",
      "args": ["C:\\github-trending-agent\\mcp\\server.py"]
    }
  }
}

Available Tools

Tool	Description
github_trending	Fetch trending with filters
github_analyze	AI analysis of repo
github_clone	Clone to workspace
github_interests	Manage keywords
github_history	View clone history

---

🔌 REST API Endpoints

Endpoint	Method	Description
/api/trending	GET	Trending repos with summaries
/api/filters	GET	Available filter options
/api/analyze	POST	Analyze a specific repo
/api/clone	POST	Clone a repo
/api/interests	GET/PUT	Manage interests
/webhook/trending	GET	For n8n/Telegram

---

🎣 Webhook Integration

# JSON format
GET http://localhost:8000/webhook/trending?format=json&limit=5

# Markdown for Telegram
GET http://localhost:8000/webhook/trending?format=markdown&limit=5

# Clone via webhook
POST http://localhost:8000/webhook/clone?repo_name=owner/repo

---

⚙️ Configuration

Edit data/interests.json:

{
  "include_keywords": ["llm", "ai", "agent", "mcp", "rag"],
  "exclude_keywords": ["supabase", "enterprise"],
  "preferred_languages": ["python", "typescript", "rust"],
  "hide_enterprise": true
}

---

📁 Project Structure

/
├── README.md                ← Main documentation
├── QUICK_START.md           ← Getting started
├── LICENSE
├── config.json              ← Configuration
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
│
├── docs/                    ← Organized documentation
│   ├── architecture.md      ← Architecture guide
│   ├── mcp-guide.md         ← MCP integration
│   └── integration.md       ← Integration guide
│
├── agent.py                 ← Main CLI entry point
├── core/                    ← Core business logic
├── mcp/                     ← MCP Server (Python)
├── api/                     ← FastAPI backend
├── dashboard/               ← Frontend (Vite + Tailwind)
├── utils/                   ← Utilities
├── tests/                   ← Tests
├── docker/                  ← Docker configs
├── data/                    ← Data files
└── skills/                  ← Skills (CLI scripts)

---

🧪 AI Summary (Ollama)

For better AI-powered summaries:

# Install Ollama from https://ollama.ai
ollama pull llama3
ollama serve

Falls back to rule-based analysis if Ollama unavailable.

---

📚 Documentation

• Architecture Guide - Technical architecture and service layer
• MCP Integration Guide - Model Context Protocol setup
• Integration Guide - How to integrate with other systems
• Quick Start - Getting started guide

---

💡 Tips

• First run: Click "Refresh" to fetch fresh data
• Interests: Mark repos "Not Interested" to improve filtering
• Cloned repos: Go to C:\github-trending-workspace\
• Claude: Use /trending workflow or MCP tools

---

Built with ❤️ for developers who want to stay on the cutting edge!