repo-seo

🚀 AI-powered GitHub SEO - Boost your repository's discoverability using X Algorithm's Two-Tower recommendation system. Optimize topics, README, and descriptions with user behavior prediction.

Architecture

Inspired by the X Algorithm's recommendation pipeline, repo-seo uses a composable pipeline architecture:

┌─────────────────────────────────────────────────────────────────────┐
│                      SEO OPTIMIZATION PIPELINE                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐   │
│   │ Sources  │────▶│Hydrators │────▶│ Filters  │────▶│ Scorers  │   │
│   │          │     │          │     │          │     │          │   │
│   │ Local    │     │ README   │     │ Quality  │     │ README   │   │
│   │ GitHub   │     │ Language │     │ Dedup    │     │ Topic    │   │
│   └──────────┘     │ Keywords │     │ Relevance│     │ SEO      │   │
│                    └──────────┘     └──────────┘     └──────────┘   │
│                                                             │       │
│                                                             ▼       │
│                                                      ┌──────────┐   │
│                                                      │ Selector │   │
│                                                      │  Top-K   │   │
│                                                      └──────────┘   │
│                                                             │       │
└─────────────────────────────────────────────────────────────│───────┘
                                                              ▼
                                                    Optimized Results

Features

• Auto-Apply SEO: Directly update GitHub topics & description with repo-seo suggest --apply
• Phoenix SEO: X Algorithm's Two-Tower + Multi-Action ranking for topic recommendations
• Pipeline Architecture: Composable sources, hydrators, filters, scorers, selectors
• Dynamic Trending Topics: Real-time GitHub trending keywords matching
• README Analysis: Section ordering suggestions, keyword optimization
• AI-Powered Analysis: OpenAI, Anthropic Claude, DeepSeek support
• Multi-Signal Scoring: README quality, topic relevance, trending score
• Rule-Based Fallback: Works without API keys

Installation

# Using uv (recommended - fastest)
uv pip install repo-seo

# Or run directly without installing
uvx repo-seo suggest

# Using pip
pip install repo-seo

# Install from source (for development)
git clone https://github.com/chenxingqiang/repo-seo.git
cd repo-seo
uv pip install -e ".[dev]"  # or: pip install -e ".[dev]"

Quick Start

Using the Pipeline (Recommended)

from repo_seo import (
    Pipeline, Query,
    LocalRepoSource,
    ReadmeHydrator,
    ReadmeScorer, TopicScorer,
    TopKSelector,
)
from repo_seo.pipeline import QualityFilter, DuplicateFilter

# Create optimization pipeline
pipeline = Pipeline(
    sources=[LocalRepoSource()],
    hydrators=[ReadmeHydrator()],
    pre_filters=[QualityFilter(), DuplicateFilter()],
    scorers=[ReadmeScorer(), TopicScorer()],
    selector=TopKSelector(k=10),
)

# Run optimization
query = Query(repo_path="./my-project", repo_name="my-project")
results = pipeline.run(query)

# Process results
for candidate in results:
    print(f"{candidate.type}: {candidate.id} (score: {candidate.final_score:.1f})")

Command Line

# SEO suggestions with README/topic analysis + auto-apply to GitHub
repo-seo suggest --top-k 10
repo-seo suggest --apply  # Actually update GitHub topics & description

# Phoenix SEO recommendations (X Algorithm style)
repo-seo phoenix --detailed

# Get trending topic suggestions
repo-seo trending --language python

# Analyze current repository
repo-seo analyze

# Optimize with AI
repo-seo optimize --repo-path . --provider openai

Auto-Apply SEO Changes

The suggest command analyzes your repo and can directly update GitHub:

# Preview suggestions
repo-seo suggest --top-k 8

# Apply changes to GitHub (updates topics + description)
repo-seo suggest --apply

Output:

📝 README Optimization Suggestions:
  1. Add [installation]: Include installation instructions
  2. Add status badges (build, coverage, version, license)

🏷️ Topic Keywords (Priority Order):
  🔥 1. api (score: 84 +20)        # +20 = content match boost
  🔥 2. machine-learning (score: 82 +20)
  📊 3. cli (score: 65)

📋 Description Optimization:
  Current:   My project...
  Suggested: AI-powered tool for X. Built with Python. Features api support.

🚀 Applying Changes to GitHub
  ✅ Topics updated successfully!
  ✅ Description updated successfully!

Simple API

from repo_seo import RepoAnalyzer

repo_info = {
    "name": "my-project",
    "description": "A sample project",
    "languages": ["Python"],
    "topics": ["python", "cli"],
    "readme": "# My Project\n\nDescription here.",
}

analyzer = RepoAnalyzer(repo_info)
results = analyzer.analyze()
print(f"SEO Score: {results['score']}/100")

Phoenix SEO (X Algorithm Style)

Topic recommendation using X Algorithm's Two-Tower architecture with Multi-Action User Behavior Prediction:

┌─────────────────────────────────────────────────────────────────┐
│                     PHOENIX SEO PIPELINE                        │
├─────────────────────────────────────────────────────────────────┤
│   ┌─────────────────┐              ┌─────────────────────────┐  │
│   │  REPO TOWER     │              │  TRENDING TOWER         │  │
│   │  (Your Repo)    │              │  (GitHub LIVE)          │  │
│   │  README         │   Dot        │  Trending Repos Topics  │  │
│   │  Description    │─ Product ───▶│  Featured Topics        │  │
│   │  Languages      │              │  (Real-time from API)   │  │
│   └─────────────────┘              └─────────────────────────┘  │
│            │                                    │               │
│            └────────────┬───────────────────────┘               │
│                         ▼                                       │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │         MULTI-ACTION USER BEHAVIOR PREDICTION           │   │
│   │  ┌────────────────────────┬────────────────────────────┐│   │
│   │  │ POSITIVE ACTIONS       │ NEGATIVE ACTIONS           ││   │
│   │  │ ⭐ P(star)             │ ⛔ P(ignore)                ││   │
│   │  │ 🍴 P(fork)             │ 🚫 P(report)                ││   │
│   │  │ 👆 P(click)            │                            ││   │
│   │  │ 👁️ P(watch)            │                            ││   │
│   │  │ 📥 P(clone)            │                            ││   │
│   │  │ 🤝 P(contribute)       │                            ││   │
│   │  └────────────────────────┴────────────────────────────┘│   │
│   │  Final Score = Σ(weight × P(positive)) - Σ(weight × P(negative))│
│   └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

from repo_seo.pipeline import PhoenixSEO, phoenix_recommend

# Quick recommendation with user behavior prediction
recommendations = phoenix_recommend(
    readme=open("README.md").read(),
    languages=["Python"],
)

for rec in recommendations:
    print(f"{rec['topic']}: Score={rec['final_score']}")
    actions = rec['action_scores']
    print(f"  ⭐ P(star)={actions['star']}  🍴 P(fork)={actions['fork']}")
    print(f"  👆 P(click)={actions['click']}  👁️ P(watch)={actions['watch']}")
    print(f"  ⛔ P(ignore)={actions['ignore']}")

CLI with detailed predictions:

repo-seo phoenix --detailed

Trending Topics

Dynamic matching with GitHub's trending keywords:

from repo_seo.pipeline import TrendingTopicSuggester, get_trending_topics

# Get trending topics for Python
topics = get_trending_topics("python", max_topics=10)
print(topics)  # ['machine-learning', 'fastapi', 'langchain', ...]

# Get personalized suggestions for your repo
suggester = TrendingTopicSuggester()
suggestions = suggester.suggest(
    repo_path="./my-project",
    current_topics=["python", "cli"],
    languages=["Python"],
    readme_content=open("README.md").read(),
)

for s in suggestions:
    print(f"{s['topic']}: {s['combined_score']:.1f}")

Pipeline Components

Component	Description
Source	Fetches candidates (LocalRepoSource, GitHubTrendingSource)
Hydrator	Enriches with features (ReadmeHydrator, TrendingHydrator)
Filter	Removes invalid items (QualityFilter, DuplicateFilter)
Scorer	Computes scores (ReadmeScorer, TopicScorer, TrendingScorer)
Selector	Picks top candidates (TopKSelector, DiversitySelector)

Find Similar Excellent Repos

Learn from top GitHub repos (5000+ stars) to optimize your topics:

# Find repos similar to yours and get topic recommendations
repo-seo similar --top-k 10

Similar repos:
  1. donnemartin/system-design-primer  333,552⭐  ████████████████████ 0.5148
  2. huggingface/transformers          155,819⭐  ███████████████████░ 0.4866

Recommended topics from similar repos:
  1. awesome (used by HelloGitHub, awesome-python)
  2. deep-learning (used by transformers, tensorflow)

Real-time Monitoring

Run a background daemon to track stars, forks, and downloads:

# Start background monitor (checks every 5 min)
repo-seo monitor --start --interval 300

# Check current metrics
repo-seo monitor

# Check monitor status
repo-seo monitor --status

# View history
repo-seo monitor --history

# Stop monitor
repo-seo monitor --stop

CLI Commands

Command	Description
repo-seo suggest --apply	Analyze & auto-apply SEO to GitHub
repo-seo phoenix --detailed	User behavior prediction (star/fork/click)
repo-seo monitor --start	Start background monitoring daemon
repo-seo mcp-server	Start MCP server for AI assistants
repo-seo retrieval	Two-Tower retrieval visualization
repo-seo similar	Find similar excellent repos
repo-seo trending	Get trending topic suggestions
repo-seo corpus	Build repo embedding corpus

MCP Server (AI Assistant Integration)

Use repo-seo as an MCP server for AI assistants like Claude in Cursor:

1. Add to Cursor MCP config (~/.cursor/mcp.json):

{
  "mcpServers": {
    "repo-seo": {
      "command": "repo-seo",
      "args": ["mcp-server"]
    }
  }
}

2. Available MCP Tools:

Tool	Description
repo_seo_suggest	Get SEO optimization suggestions
repo_seo_phoenix	Run Two-Tower + behavior prediction
repo_seo_trending	Get trending topics
repo_seo_similar	Find similar excellent repos
repo_seo_monitor	Check metrics and monitoring
repo_seo_analyze	Analyze README quality
repo_seo_set_api_key	Set API key (OPENAI, ANTHROPIC, etc.)
repo_seo_get_config	View current configuration
repo_seo_list_providers	List LLM providers and status
repo_seo_delete_api_key	Remove a stored API key
repo_seo_github_auth	Check/set GitHub authentication

3. Or run standalone:

repo-seo mcp-server
# or
repo-seo-mcp

Configuration

# Set API keys (optional - works without them)
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

Development

pip install -e ".[dev]"
pytest
ruff check repo_seo/

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

License

MIT License - see LICENSE for details.

---

⭐ Star this repo if it helps you!
https://github.com/chenxingqiang/repo-seo