{"id":26436263,"url":"https://github.com/chenxingqiang/repo-seo","last_synced_at":"2026-07-16T14:34:48.641Z","repository":{"id":271687325,"uuid":"914257415","full_name":"chenxingqiang/repo-seo","owner":"chenxingqiang","description":"🚀 AI-powered GitHub SEO: Boost repo discoverability with X Algorithm's Two-Tower recommendation. Topics, README optimization \u0026 user behavior prediction.","archived":false,"fork":false,"pushed_at":"2026-01-27T17:54:07.000Z","size":1380,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-28T03:41:46.718Z","etag":null,"topics":["ai","api","automation","bash","cli","developer-tools","development","discoverability","github-seo","langchain","library","markdown","openai","optimization","python","recommendation-system","repo","seo","tool"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chenxingqiang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-09T08:48:38.000Z","updated_at":"2026-01-27T17:54:15.000Z","dependencies_parsed_at":"2025-01-09T09:54:06.754Z","dependency_job_id":"28db22c2-74f8-4681-b563-b13a7add5c14","html_url":"https://github.com/chenxingqiang/repo-seo","commit_stats":null,"previous_names":["chenxingqiang/repo-seo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/chenxingqiang/repo-seo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenxingqiang%2Frepo-seo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenxingqiang%2Frepo-seo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenxingqiang%2Frepo-seo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenxingqiang%2Frepo-seo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chenxingqiang","download_url":"https://codeload.github.com/chenxingqiang/repo-seo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenxingqiang%2Frepo-seo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35547971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-16T02:00:06.687Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","api","automation","bash","cli","developer-tools","development","discoverability","github-seo","langchain","library","markdown","openai","optimization","python","recommendation-system","repo","seo","tool"],"created_at":"2025-03-18T08:15:57.847Z","updated_at":"2026-07-16T14:34:48.636Z","avatar_url":"https://github.com/chenxingqiang.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# repo-seo\n\n[![PyPI version](https://badge.fury.io/py/repo-seo.svg)](https://pypi.org/project/repo-seo/)\n[![Downloads](https://static.pepy.tech/badge/repo-seo)](https://pepy.tech/project/repo-seo)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/)\n[![GitHub stars](https://img.shields.io/github/stars/chenxingqiang/repo-seo?style=social)](https://github.com/chenxingqiang/repo-seo)\n\n🚀 **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.\n\n## Architecture\n\nInspired by the **X Algorithm's** recommendation pipeline, repo-seo uses a composable pipeline architecture:\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                      SEO OPTIMIZATION PIPELINE                      │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│   ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐   │\n│   │ Sources  │────▶│Hydrators │────▶│ Filters  │────▶│ Scorers  │   │\n│   │          │     │          │     │          │     │          │   │\n│   │ Local    │     │ README   │     │ Quality  │     │ README   │   │\n│   │ GitHub   │     │ Language │     │ Dedup    │     │ Topic    │   │\n│   └──────────┘     │ Keywords │     │ Relevance│     │ SEO      │   │\n│                    └──────────┘     └──────────┘     └──────────┘   │\n│                                                             │       │\n│                                                             ▼       │\n│                                                      ┌──────────┐   │\n│                                                      │ Selector │   │\n│                                                      │  Top-K   │   │\n│                                                      └──────────┘   │\n│                                                             │       │\n└─────────────────────────────────────────────────────────────│───────┘\n                                                              ▼\n                                                    Optimized Results\n```\n\n## Features\n\n- **Auto-Apply SEO**: Directly update GitHub topics \u0026 description with `repo-seo suggest --apply`\n- **Phoenix SEO**: X Algorithm's Two-Tower + Multi-Action ranking for topic recommendations\n- **Pipeline Architecture**: Composable sources, hydrators, filters, scorers, selectors\n- **Dynamic Trending Topics**: Real-time GitHub trending keywords matching\n- **README Analysis**: Section ordering suggestions, keyword optimization\n- **AI-Powered Analysis**: OpenAI, Anthropic Claude, DeepSeek support\n- **Multi-Signal Scoring**: README quality, topic relevance, trending score\n- **Rule-Based Fallback**: Works without API keys\n\n## Installation\n\n```bash\n# Using uv (recommended - fastest)\nuv pip install repo-seo\n\n# Or run directly without installing\nuvx repo-seo suggest\n\n# Using pip\npip install repo-seo\n\n# Install from source (for development)\ngit clone https://github.com/chenxingqiang/repo-seo.git\ncd repo-seo\nuv pip install -e \".[dev]\"  # or: pip install -e \".[dev]\"\n```\n\n## Quick Start\n\n### Using the Pipeline (Recommended)\n\n```python\nfrom repo_seo import (\n    Pipeline, Query,\n    LocalRepoSource,\n    ReadmeHydrator,\n    ReadmeScorer, TopicScorer,\n    TopKSelector,\n)\nfrom repo_seo.pipeline import QualityFilter, DuplicateFilter\n\n# Create optimization pipeline\npipeline = Pipeline(\n    sources=[LocalRepoSource()],\n    hydrators=[ReadmeHydrator()],\n    pre_filters=[QualityFilter(), DuplicateFilter()],\n    scorers=[ReadmeScorer(), TopicScorer()],\n    selector=TopKSelector(k=10),\n)\n\n# Run optimization\nquery = Query(repo_path=\"./my-project\", repo_name=\"my-project\")\nresults = pipeline.run(query)\n\n# Process results\nfor candidate in results:\n    print(f\"{candidate.type}: {candidate.id} (score: {candidate.final_score:.1f})\")\n```\n\n### Command Line\n\n```bash\n# SEO suggestions with README/topic analysis + auto-apply to GitHub\nrepo-seo suggest --top-k 10\nrepo-seo suggest --apply  # Actually update GitHub topics \u0026 description\n\n# Phoenix SEO recommendations (X Algorithm style)\nrepo-seo phoenix --detailed\n\n# Get trending topic suggestions\nrepo-seo trending --language python\n\n# Analyze current repository\nrepo-seo analyze\n\n# Optimize with AI\nrepo-seo optimize --repo-path . --provider openai\n```\n\n### Auto-Apply SEO Changes\n\nThe `suggest` command analyzes your repo and can directly update GitHub:\n\n```bash\n# Preview suggestions\nrepo-seo suggest --top-k 8\n\n# Apply changes to GitHub (updates topics + description)\nrepo-seo suggest --apply\n```\n\n**Output:**\n```\n📝 README Optimization Suggestions:\n  1. Add [installation]: Include installation instructions\n  2. Add status badges (build, coverage, version, license)\n\n🏷️ Topic Keywords (Priority Order):\n  🔥 1. api (score: 84 +20)        # +20 = content match boost\n  🔥 2. machine-learning (score: 82 +20)\n  📊 3. cli (score: 65)\n\n📋 Description Optimization:\n  Current:   My project...\n  Suggested: AI-powered tool for X. Built with Python. Features api support.\n\n🚀 Applying Changes to GitHub\n  ✅ Topics updated successfully!\n  ✅ Description updated successfully!\n```\n\n### Simple API\n\n```python\nfrom repo_seo import RepoAnalyzer\n\nrepo_info = {\n    \"name\": \"my-project\",\n    \"description\": \"A sample project\",\n    \"languages\": [\"Python\"],\n    \"topics\": [\"python\", \"cli\"],\n    \"readme\": \"# My Project\\n\\nDescription here.\",\n}\n\nanalyzer = RepoAnalyzer(repo_info)\nresults = analyzer.analyze()\nprint(f\"SEO Score: {results['score']}/100\")\n```\n\n## Phoenix SEO (X Algorithm Style)\n\nTopic recommendation using X Algorithm's Two-Tower architecture with **Multi-Action User Behavior Prediction**:\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                     PHOENIX SEO PIPELINE                        │\n├─────────────────────────────────────────────────────────────────┤\n│   ┌─────────────────┐              ┌─────────────────────────┐  │\n│   │  REPO TOWER     │              │  TRENDING TOWER         │  │\n│   │  (Your Repo)    │              │  (GitHub LIVE)          │  │\n│   │  README         │   Dot        │  Trending Repos Topics  │  │\n│   │  Description    │─ Product ───▶│  Featured Topics        │  │\n│   │  Languages      │              │  (Real-time from API)   │  │\n│   └─────────────────┘              └─────────────────────────┘  │\n│            │                                    │               │\n│            └────────────┬───────────────────────┘               │\n│                         ▼                                       │\n│   ┌─────────────────────────────────────────────────────────┐   │\n│   │         MULTI-ACTION USER BEHAVIOR PREDICTION           │   │\n│   │  ┌────────────────────────┬────────────────────────────┐│   │\n│   │  │ POSITIVE ACTIONS       │ NEGATIVE ACTIONS           ││   │\n│   │  │ ⭐ P(star)             │ ⛔ P(ignore)                ││   │\n│   │  │ 🍴 P(fork)             │ 🚫 P(report)                ││   │\n│   │  │ 👆 P(click)            │                            ││   │\n│   │  │ 👁️ P(watch)            │                            ││   │\n│   │  │ 📥 P(clone)            │                            ││   │\n│   │  │ 🤝 P(contribute)       │                            ││   │\n│   │  └────────────────────────┴────────────────────────────┘│   │\n│   │  Final Score = Σ(weight × P(positive)) - Σ(weight × P(negative))│\n│   └─────────────────────────────────────────────────────────┘   │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n```python\nfrom repo_seo.pipeline import PhoenixSEO, phoenix_recommend\n\n# Quick recommendation with user behavior prediction\nrecommendations = phoenix_recommend(\n    readme=open(\"README.md\").read(),\n    languages=[\"Python\"],\n)\n\nfor rec in recommendations:\n    print(f\"{rec['topic']}: Score={rec['final_score']}\")\n    actions = rec['action_scores']\n    print(f\"  ⭐ P(star)={actions['star']}  🍴 P(fork)={actions['fork']}\")\n    print(f\"  👆 P(click)={actions['click']}  👁️ P(watch)={actions['watch']}\")\n    print(f\"  ⛔ P(ignore)={actions['ignore']}\")\n```\n\n**CLI with detailed predictions:**\n```bash\nrepo-seo phoenix --detailed\n```\n\n## Trending Topics\n\nDynamic matching with GitHub's trending keywords:\n\n```python\nfrom repo_seo.pipeline import TrendingTopicSuggester, get_trending_topics\n\n# Get trending topics for Python\ntopics = get_trending_topics(\"python\", max_topics=10)\nprint(topics)  # ['machine-learning', 'fastapi', 'langchain', ...]\n\n# Get personalized suggestions for your repo\nsuggester = TrendingTopicSuggester()\nsuggestions = suggester.suggest(\n    repo_path=\"./my-project\",\n    current_topics=[\"python\", \"cli\"],\n    languages=[\"Python\"],\n    readme_content=open(\"README.md\").read(),\n)\n\nfor s in suggestions:\n    print(f\"{s['topic']}: {s['combined_score']:.1f}\")\n```\n\n## Pipeline Components\n\n| Component | Description |\n|-----------|-------------|\n| **Source** | Fetches candidates (LocalRepoSource, GitHubTrendingSource) |\n| **Hydrator** | Enriches with features (ReadmeHydrator, TrendingHydrator) |\n| **Filter** | Removes invalid items (QualityFilter, DuplicateFilter) |\n| **Scorer** | Computes scores (ReadmeScorer, TopicScorer, TrendingScorer) |\n| **Selector** | Picks top candidates (TopKSelector, DiversitySelector) |\n\n## Find Similar Excellent Repos\n\nLearn from top GitHub repos (5000+ stars) to optimize your topics:\n\n```bash\n# Find repos similar to yours and get topic recommendations\nrepo-seo similar --top-k 10\n```\n\n```\nSimilar repos:\n  1. donnemartin/system-design-primer  333,552⭐  ████████████████████ 0.5148\n  2. huggingface/transformers          155,819⭐  ███████████████████░ 0.4866\n\nRecommended topics from similar repos:\n  1. awesome (used by HelloGitHub, awesome-python)\n  2. deep-learning (used by transformers, tensorflow)\n```\n\n## Real-time Monitoring\n\nRun a background daemon to track stars, forks, and downloads:\n\n```bash\n# Start background monitor (checks every 5 min)\nrepo-seo monitor --start --interval 300\n\n# Check current metrics\nrepo-seo monitor\n\n# Check monitor status\nrepo-seo monitor --status\n\n# View history\nrepo-seo monitor --history\n\n# Stop monitor\nrepo-seo monitor --stop\n```\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `repo-seo suggest --apply` | Analyze \u0026 auto-apply SEO to GitHub |\n| `repo-seo phoenix --detailed` | User behavior prediction (star/fork/click) |\n| `repo-seo monitor --start` | Start background monitoring daemon |\n| `repo-seo mcp-server` | Start MCP server for AI assistants |\n| `repo-seo retrieval` | Two-Tower retrieval visualization |\n| `repo-seo similar` | Find similar excellent repos |\n| `repo-seo trending` | Get trending topic suggestions |\n| `repo-seo corpus` | Build repo embedding corpus |\n\n## MCP Server (AI Assistant Integration)\n\nUse repo-seo as an MCP server for AI assistants like Claude in Cursor:\n\n**1. Add to Cursor MCP config (`~/.cursor/mcp.json`):**\n\n```json\n{\n  \"mcpServers\": {\n    \"repo-seo\": {\n      \"command\": \"repo-seo\",\n      \"args\": [\"mcp-server\"]\n    }\n  }\n}\n```\n\n**2. Available MCP Tools:**\n\n| Tool | Description |\n|------|-------------|\n| `repo_seo_suggest` | Get SEO optimization suggestions |\n| `repo_seo_phoenix` | Run Two-Tower + behavior prediction |\n| `repo_seo_trending` | Get trending topics |\n| `repo_seo_similar` | Find similar excellent repos |\n| `repo_seo_monitor` | Check metrics and monitoring |\n| `repo_seo_analyze` | Analyze README quality |\n| `repo_seo_set_api_key` | Set API key (OPENAI, ANTHROPIC, etc.) |\n| `repo_seo_get_config` | View current configuration |\n| `repo_seo_list_providers` | List LLM providers and status |\n| `repo_seo_delete_api_key` | Remove a stored API key |\n| `repo_seo_github_auth` | Check/set GitHub authentication |\n\n**3. Or run standalone:**\n\n```bash\nrepo-seo mcp-server\n# or\nrepo-seo-mcp\n```\n\n## Configuration\n\n```bash\n# Set API keys (optional - works without them)\nexport OPENAI_API_KEY=sk-...\nexport ANTHROPIC_API_KEY=sk-ant-...\n```\n\n## Development\n\n```bash\npip install -e \".[dev]\"\npytest\nruff check repo_seo/\n```\n\n## Contributing\n\nContributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003e⭐ Star this repo if it helps you!\u003c/b\u003e\u003cbr\u003e\n  \u003ca href=\"https://github.com/chenxingqiang/repo-seo\"\u003ehttps://github.com/chenxingqiang/repo-seo\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchenxingqiang%2Frepo-seo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchenxingqiang%2Frepo-seo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchenxingqiang%2Frepo-seo/lists"}