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

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

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:

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