⚡ X Algorithm Toolkit

Score, optimize, and generate tweets using the actual signal weights from X's open-source recommendation algorithm.

🧠 What This Does

This toolkit reverse-engineers X's recommendation algorithm from the open-source codebase and gives you:

• Tweet Scorer — Score any draft (0-100) against the actual algorithm weights

• Hook Analyzer — Test your opening line against the -11× not_dwelled penalty

• Diversity Calculator — Plan posting cadence using the decay formula from author_diversity_scorer.rs

• 18 Filter Checker — Run tweets through quality/safety gates

• AI Rewrite, Generate & Thread Builder — Multi-provider AI (Groq, Gemini, OpenAI, Claude)

• Draft Manager, Compare Mode, Score History — Full workflow tools

• Export Scorecard — Branded PNG downloads

📊 The 22 Algorithm Signals

From weighted_scorer.rs + ranking_scorer.rs:

+ 13 more signals (Like, Repost, Quote, Quoted Click, Share, DM Share, Copy Link, Click, Profile Click, Photo Expand, Video Quality View)

🚀 Quick Start

# Clone
git clone https://github.com/MrChartist/x-algorithm-toolkit.git
cd x-algorithm-toolkit

# Install & Run
npm install
npm run dev

Open http://localhost:5173 — no API key needed for scoring, filters, and analysis.

For AI features (Rewrite, Generate, Thread), add an API key in Settings (Groq free tier recommended).

🔧 MCP Server (npm)

Install the MCP server to connect the algorithm engine to any AI assistant:

Option 1: Via npx (Recommended)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "x-algorithm": {
      "command": "npx",
      "args": ["-y", "x-algorithm-mcp"]
    }
  }
}

Option 2: Global Install

npm install -g x-algorithm-mcp

Option 3: From Source

cd mcp && npm install && npm run build

11 Tools: score_tweet, check_filters, analyze_hook, get_signals, get_optimal_schedule, compare_tweets, detect_spam_patterns, diversity_penalty, classify_niche, get_thread_strategy, full_audit

3 Resources: x-algorithm://weights, x-algorithm://filters, x-algorithm://niches

🎯 AI Skill (Antigravity / Gemini CLI)

400+ lines of domain expertise that makes any AI an X algorithm expert:

Install Globally

mkdir -p ~/.gemini/antigravity/skills/x-algorithm-expert
curl -o ~/.gemini/antigravity/skills/x-algorithm-expert/SKILL.md \
  https://raw.githubusercontent.com/MrChartist/x-algorithm-toolkit/master/skill/SKILL.md

What's Covered:

• All 22 signal weights with optimization strategies

• Phoenix Grok-based transformer architecture

• 77+ topic categories from topic_ids_filter.rs

• 10-point scoring system with letter grades

• Hook writing rules and 7 templates

• Author diversity decay formula

• OON viral mechanics

• Thread building strategy (6 templates)

• 18 safety filter checklist

• Niche-specific optimization (7 niches)

📁 Architecture

x-algo-toolkit/
├── src/                    # React Web App (13 tabs)
│   ├── engine/             # Scoring engine + AI abstraction
│   └── components/         # 15 UI components
├── mcp/                    # MCP Server (11 tools, 3 resources)
│   ├── src/                # TypeScript source
│   ├── dist/               # Compiled output
│   └── package.json        # npm: x-algorithm-mcp
├── skill/                  # AI Skill
│   └── SKILL.md            # 400+ line expertise file
└── public/                 # Static assets

🛠️ Tech Stack

• Frontend: React 19, TypeScript, Vite

• Animations: Framer Motion

• AI: Multi-provider (Groq/Gemini/OpenAI/Claude)

• MCP: @modelcontextprotocol/sdk v1.12+

• Storage: localStorage (no backend needed)

📜 License

MIT — Built by @Mr_Chartist

Data sourced from X's open-source algorithm: weighted_scorer.rs, ranking_scorer.rs, author_diversity_scorer.rs, oon_scorer.rs, topic_ids_filter.rs, recsys_model.py