superx.free
Open-source, self-hosted growth workstation for X (Twitter). Learns your voice, drafts from high-performing posts, schedules and publishes. Bring your own API keys.
Install / Use
claude mcp add ashishbishnoi18 -- npx -y github:ashishbishnoi18/superx.freeIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AutomationSupported Platforms
Our assessment of superx.free
superx.free scores 83/100 on our quality scale, 2150th of 2,790 Automation skills we index.
Its MCP Server is 8.6 KB long, well organised into 10 sections with 4 code examples: a thorough specification that gives an agent plenty to work with.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 37 days ago, so superx.free is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-14. Automated pattern scan on 2026-11-14. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
superx.free compared with similar skills
All 4 of these similar skills score higher than superx.free; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| superx.free (this skill)by ashishbishnoi18 | 83 | 10 | 37d ago | MCP Server |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| CowAgentby zhayujie | 100 | 48.0k | today | CLAUDE.md |
Frequently asked questions
- How do I install superx.free?
- Run
claude mcp add ashishbishnoi18 -- npx -y github:ashishbishnoi18/superx.free. The install tabs above show the steps for each supported agent. - Which AI agents does superx.free work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is superx.free safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is superx.free still maintained?
- The repository was last updated 37 days ago, so superx.free is actively maintained.
Skill content
View source on GitHubSuperX
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:
| | | |---|---| | $5/month | You bring your own X and model keys. | | $9/month | Runs on ours. Nothing else to sign up for. |
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.
| | For | Cost | |---|---|---| | X developer app | Sign-in and publishing | Pay per use — about $0.015 a post, no free tier | | twitterapi.io | The corpus, mentions, feeds, Signals | ~$0.15 per 1,000 posts read | | An LLM key | Drafting, replies, scoring | DeepSeek or Anthropic; a few dollars a month |
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.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
CowAgent
48.0kOpen-source personal AI assistant & Agent Harness. Plans tasks, runs tools and skills, self-evolves with memory and knowledge. Multi-agent, multi-model, multi-channel. Lightweight, extensible, one-line install.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
