⚡ 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`*