# Overview

tweet-factory is a local [Bun](https://bun.sh) + TypeScript CLI, `tf`. It learns from one X account’s likes, bookmarks, and posts, stores them in SQLite, and drafts new tweets in that person’s voice with their own LLM.

The project directory is the product. Local files are the default. Optional [cloud sync](cloud-sync.md) (`tf login`, then `tf sync push`) copies that directory to a tweetfactory.sh account. Nothing is uploaded until you push.

## What a run actually does

1. `tf auth` completes OAuth 2.0 (PKCE) and writes `.tokens.json`.
2. `tf fetch` pulls likes, bookmarks, and the account’s own posts into `tweets.db`.
3. A persona file, `persona/PERSONA.md`, records voice rules. `tf onboard` can write it, or you edit the template.
4. `tf generate` asks your LLM for four ideas, each with two or three variants. The prompt includes measured voice stats, your reply/quote/repost/like rates when `tweets.db` has enough impressions, and the published For You weights ([`xai-org/x-algorithm`](https://github.com/xai-org/x-algorithm) commit [`cb45b55`](https://github.com/xai-org/x-algorithm/commit/cb45b55)). `drafts/YYYY-MM-DD.md` shows a per-head breakdown and a 0–100 score, and tells you to post one variant.
5. `tf refresh` refreshes the database and writes what’s new to `flush/pending.md`. It does not call an LLM. `tf update` is separate: it replaces a release binary.

You publish the drafts yourself. `tf` never posts to X.

## How the For You ranker is described here

These pages quote [`X_ALGORITHM_BOOST_PLAYBOOK.md`](https://github.com/abhirupghosh/tweet-factory/blob/main/X_ALGORITHM_BOOST_PLAYBOOK.md), which was checked against [`xai-org/x-algorithm`](https://github.com/xai-org/x-algorithm) commit [`cb45b55`](https://github.com/xai-org/x-algorithm/commit/cb45b55) (2026-10-09). They do not add engagement statistics that file does not contain.

- [How the X (Twitter) algorithm works](how-the-x-algorithm-works.md)
- [X algorithm changes in 2026](x-algorithm-changes-2026.md)
- [How to grow on X](x-algorithm-engagement-weights.md)
- [Best time to post on X](best-time-to-post-on-x.md)
- [Myths: links, hashtags, bookmarks, Premium](x-algorithm-myths.md)
- [Shadowban on X: what the code filters](shadowban-on-x.md)
- [Tweet reply generator](why-replies-stay-in-network.md)
- [How to reset your X algorithm](how-to-reset-your-x-algorithm.md)
- [How tweet-factory scores drafts](how-tweet-factory-scores-drafts.md)
- [What is TweepCred](what-is-tweepcred.md)
- [Twitter algorithm on GitHub](twitter-algorithm-github.md)
- [Tweet generator in your voice](ai-tweet-writer-your-voice.md)
- [Using tweet-factory with Claude Code](claude-code-twitter.md)
- [Compared with Typefully, Tweet Hunter, and Hypefury](compare-typefully-tweet-hunter-hypefury.md)
- [Typefully alternative](typefully-alternative.md)
- [Tweet Hunter alternative](tweet-hunter-alternative.md)
- [Hypefury alternative](hypefury-alternative.md)

## Start here

- A person installing it: [Install](install.md), then [X app setup](x-app.md).
- A coding agent installing it for someone: [copy-paste prompt](agent-prompt.md), then the [runbook](agent.md).
- Machine-readable index: [/llms.txt](/llms.txt). Full text of every page: [/llms-full.txt](/llms-full.txt). Each HTML page also has a markdown twin (`/install.md`, and `/install/index.md`).

## Files that matter

| Path | Role |
|---|---|
| `tweets.db` | Likes, bookmarks, your posts, article text, tagged Notion pages |
| `persona/PERSONA.md` | Voice source of truth. Gitignored once filled in |
| `flush/pending.md` | New interactions since the last flush commit |
| `drafts/YYYY-MM-DD.md` | Scored drafts |
| `onboarding.json` | Structured bundle from the last `tf generate` |
| `.env` | API keys. Mode should be `0600` |
| `.tokens.json` | OAuth tokens. Written mode `0600` |
| `.cloud.json` | Optional cloud-sync device token. Written mode `0600` by `tf login`. Absent until you link |
| `X_ALGORITHM_BOOST_PLAYBOOK.md` | Human-readable ranker write-up. Scoring uses `src/rank/weights.ts` |

Install the release binary with the command on [Install](install.md): `curl -fsSL https://tweetfactory.sh/install.sh | sh`. The site build serves that script. It downloads `tf-darwin-arm64`, `tf-darwin-x64`, `tf-linux-x64`, or `tf-linux-arm64` from `https://tweetfactory.sh/download/vX.Y.Z/` and checks `SHA256SUMS`. The current tag is `https://tweetfactory.sh/download/latest/VERSION`. The repository is private. All rights reserved.