SuperX

SuperX

An open-source, self-hosted growth workstation for X (Twitter). It learns how you write, finds posts worth learning from, drafts in your voice, and publishes on a schedule you set.

A free alternative to hosted tools like superx.so, Hypefury and Typefully — except it runs on your own machine, with your own API keys, and nothing leaves the box.

git clone https://github.com/ashishbishnoi18/superx.free.git superx && cd superx
cp .env.example .env      # add your keys — see docs/SETUP.md
docker compose up -d --build

Then open http://localhost:4000 and sign in with X.

• Setup, step by step → docs/SETUP.md
• Every environment variable → docs/CONFIGURATION.md
• Running it in production → docs/DEPLOYMENT.md
• How it works and why → docs/ARCHITECTURE.md
• When something breaks → docs/TROUBLESHOOTING.md
• Costs and common questions → docs/FAQ.md

Or let someone else run it

Self-hosting is the point of this project and is free forever. If you would rather not keep a server alive, superx.free runs this same codebase, at this commit:

Paying unlocks nothing. The software is identical either way and the source is right here — it pays for the machine and, on the second price, the API bills it runs up. Cancel from inside the app whenever you like.

Why this exists

Posting consistently on X is mostly a scheduling and memory problem, and the tools that solve it charge $49–199 a month to hold your OAuth token, your drafts, and your audience data on their servers.

Self-hosted, everything runs on one box you control. There is no telemetry, no analytics pixel, no account to create, and no vendor who can change the price or read your drafts. You bring your own API keys — the same ones the hosted tools use on your behalf — and pay the underlying providers directly, which is a few dollars a month rather than a few hundred.

The hosted instance above is a convenience, not the product. It is the same code, it is priced at roughly what it costs to run, and the escape hatch is a git clone rather than an export request.

What it does

Create — Derives a voice profile from your own posts, retrieves a high-performing post from a shared corpus, and rewrites its structure onto one of your topics in your voice. Drafts land on an approval shelf; nothing publishes without you accepting it. The composer autosaves drafts as you type and can tighten a draft in your voice with a one-credit "improve" pass.

Queue — Recurring weekly slots in your local time. Approved drafts fill the next opening and publish automatically, with retries, DST-correct scheduling, and a visible failure state when X refuses. Optional random publish delay (up to 5 minutes) so posts don't fire at exact minutes, and tags to organise and filter drafts. Per-post automations, always explicit opt-ins set on the post itself: repost after N hours (and undo it later), reply with a plug once the post hits a like threshold, or delete the post if it stays under a views floor.

Workers — Named, configurable generators. Pick a voice, a topic source and a batch size; run on demand or on a schedule. Output goes to the same approval shelf.

Engage — Mentions and topic feeds in one inbox. Mentions are scored 0–100 for whether they are worth answering and ordered by that, with filters on likes, author followers, verification and mention type; feeds read newest first and can exclude whole topic categories. Replies are drafted in your voice and send immediately, because a reply two days late is not a reply. Sent replies track their own likes and views.

Signals — Standing watches on X: posts matching a search, followers of an account, people replying to an account, people posting in a list. Each scores whoever it finds against a sentence describing who you are looking for, and files the keepers in Contacts.

Contacts — Lists, CSV export, and a revocable public link if you want to share one.

Inspiration — Search the corpus of high-performing posts. Full-text always, vector similarity when embeddings are configured, plus filters on engagement, length and date. Outlier detection scores how far a post beat the median for its author's follower band, so a 3× post from a small account outranks a bigger post that merely had reach.

Analytics — Nightly snapshots, follower trend, posting streak, and an estimate of which posts drew followers. Import your X analytics export to backfill history.

Ask — Chat with tools over your own data: analytics, queue, shelf, inbox, contacts, feeds, articles and the library. It can create drafts on Ready to Post. Scheduling and publishing require a deterministic user action.

Articles — Long-form composition with AI assistance, review, and explicit publishing through X's Articles API.

API, MCP and CLI — A read-write HTTP API, an MCP server so Claude Code, Codex or ChatGPT can drive your account directly, and a zero-dependency CLI.

What it deliberately does not do

Honest limitations, because you will find them anyway:

• It never publishes without your approval. There is no autopilot, and the API and MCP surfaces stop at queueing on purpose.
• No group DM replies. Legacy and encrypted XChat one-to-one threads share the inbox. Group conversations are skipped because there is no single safe participant address for a reply.
• Encrypted DMs sent before you connected stay unreadable. XChat gives a conversation key to the devices registered at the time. This instance registers its own on first sync, so it can read everything from that moment and nothing from before it. No copy of the history exists to decrypt.
• Articles need X Premium. The API rejects long-form publishing without it, and says so plainly when you try.
• The corpus starts empty and fills at ~800 posts a night. A hosted competitor hands you millions on day one; you build yours.
• No bulk DM outreach. Sending automated DMs to strangers is the one feature here that would mostly be used for spam.

Stack

browser
  → Phoenix LiveView
  → Postgres          (data, job queue, vector store, pub/sub)
  → Oban              (scheduling, publishing, ingestion, generation)
  → twitterapi.io     (public reads: corpus, mentions, feeds, watches)
  → X API v2          (writes, and private DM reads, with your OAuth token)
  → Node + Chat XDK   (local XChat encryption, decryption, and signing)

No Redis, no separate queue service, no separate scheduler, no external cache. Postgres is all of them. Web, workers and cron run as one supervised OS process on one box.

See docs/ARCHITECTURE.md for why the read and write paths use different providers.

What you need

Three keys, all obtainable in a few minutes. Full walkthrough in docs/SETUP.md.

Each is optional and degrades rather than breaks. No LLM key means no drafting, but the queue and scheduling still work. No twitterapi.io key means no corpus or feeds, but you can still write and publish.

Running cost for one person is typically $5–15 a month paid directly to those providers. See docs/FAQ.md for the arithmetic.

Local development

Needs Elixir 1.19 and Postgres 17+ with pgvector. XChat additionally needs Node 18+ and npm ci in xchat/; it stays disabled when either is absent.

mix setup
mix superx.dev.seed     # demo user, corpus, shelf, analytics
mix phx.server

The seed prints a sign-in URL, so you can exercise every screen without X or LLM credentials.

mix test          # 357 tests
mix precommit     # format, compile with warnings as errors, test

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for how the codebase is written — in particular, comments here explain why rather than what, and tests concentrate on the paths that spend money or lose data.

Security issues: please read SECURITY.md rather than opening a public issue.

Licence

MIT. See LICENSE.