flowchart TD
    subgraph Input["Input Channels"]
        Studio["🎨 Google Material 3 Studio<br/>(public/index.html)"]
        CLI["💻 Omnipost CLI"]
        MCP["🤖 AI Agent MCP Clients<br/>(Claude, Cursor, Cline, Zed)"]
        PyAPI["🐍 Python SDK / API"]
    end

    subgraph Core["Omnipost Social Engine Core"]
        Tokenizer["AST Tokenizer & Thread Splitter"]
        UnicodeEngine["Unicode Mathematical Typography"]
        ViralityScorer["Algorithmic Virality Diagnostics"]
        EnvelopeEngine["Platform Envelope Translators"]
        RateLimiter["Leaky Bucket Async Token Bucket"]
    end

    subgraph Outputs["Target Platforms"]
        TW["𝕏 / Twitter (280 chars)"]
        LI["💼 LinkedIn (3000 chars)"]
        BS["🦋 BlueSky ATProto (300 chars)"]
        TH["🧵 Threads (500 chars)"]
        MA["🐘 Mastodon Fediverse (500 chars)"]
    end

    Studio --> Core
    CLI --> Core
    MCP --> Core
    PyAPI --> Core

    Core --> TW
    Core --> LI
    Core --> BS
    Core --> TH
    Core --> MA

# Clone the repository
git clone https://github.com/omnipost/omnipost-social-engine.git
cd omnipost-social-engine

# Install in editable mode
pip install -e .

# macOS
open public/index.html

# Linux
xdg-open public/index.html

# Windows
start public/index.html

from omnipost_social_engine import OmnipostEngine

engine = OmnipostEngine()

draft = """
🚀 We just open-sourced Omnipost Social Engine!

One unified Python library to compose, simulate, and broadcast across:
• Twitter / X
• LinkedIn
• BlueSky & Threads

Star the repo on GitHub 👇
#Python #OpenSource
"""

result = engine.score_virality(draft, platform="twitter")
print(f"Virality Score: {result.score}/100 ({result.grade})")
print(f"Hook Strength: {result.factors.hook_power}/30")

essay = Path("article.md").read_text()

thread = engine.split_thread(
    source_text=essay,
    max_chars_per_post=280,
    numbering_style="fraction", # (1/N)
    auto_hook=True,
    auto_cta=True
)

for post in thread.posts:
    print(f"[{post.order}/{len(thread.posts)}] ({len(post.text)} chars):\n{post.text}\n---")

{
  "mcpServers": {
    "omnipost-social-engine": {
      "command": "python",
      "args": ["-m", "omnipost_social_engine.mcp_server"],
      "env": {
        "PYTHONPATH": "src"
      }
    }
  }
}

omnipost-social-engine/
├── .github/
│   └── workflows/
│       ├── ci.yml              # 15-job matrix (Ubuntu, macOS, Win / Python 3.9-3.13)
│       └── release.yml         # Wheel/sdist packaging, SHA256, PyPI & GitHub Release
├── docs/
│   ├── MCP_GUIDE.md            # Model Context Protocol manual & tool schemas
│   ├── PLATFORM_LIMITS_GUIDE.md# Platform rate limits, character specs & media matrix
│   └── VIRAL_HOOK_FORMULAS.md  # 15+ psychological copywriting formulas & heuristics
├── examples/
│   ├── README.md               # Master examples catalog
│   ├── developer-thread/       # 10-part technical developer thread example
│   │   ├── thread.md
│   │   └── README.md
│   ├── launch-campaign/        # Complete omnichannel product launch dataset
│   │   ├── campaign.json
│   │   ├── posts.csv
│   │   └── README.md
│   └── mcp-clients/            # Pre-built configs for Claude, Cursor, Cline, Zed
│       ├── claude_desktop_config.json
│       ├── cursor_mcp.json
│       ├── cline_mcp.json
│       ├── zed_settings.json
│       └── README.md
├── public/
│   └── index.html              # Google Material 3 Studio single-page application
├── src/
│   └── omnipost_social_engine/ # Core engine Python package
└── tests/
    └── test_examples.py        # Validation test suite for UI, examples & docs

PYTHONPATH=src pytest tests/ -v