# tweet-factory documentation

> Concatenation of the markdown pages linked from https://docs.tweetfactory.sh/llms.txt

---

Source: https://docs.tweetfactory.sh/index.md

# 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.

---

Source: https://docs.tweetfactory.sh/agent-prompt.md

# Copy-paste setup prompt

Paste this to a coding agent in the environment where tweet-factory should run. The agent clones the repo, follows the runbook, and stops where a person has to click or paste a key.

```prompt
Set up tweet-factory on this machine for me.

Read these first, in order, and follow them:
1. https://docs.tweetfactory.sh/llms.txt
2. https://docs.tweetfactory.sh/agent.md
3. https://docs.tweetfactory.sh/install.md
4. https://docs.tweetfactory.sh/x-app.md

agent.md is the same runbook as SETUP.md in https://github.com/abhirupghosh/tweet-factory (plus this prompt). When a step and the repo disagree, trust the repo source and say so.

Rules:
- Install tf with the command in https://docs.tweetfactory.sh/install.md. Do not clone the repo unless the user already has a checkout or asked to develop from source.
- If a checkout is already on this machine, stay in it and use ./setup_x.sh. Do not delete it.
- Never invent credentials, tokens, or API keys. Never print secret values back to me.
- Write secrets only into .env. After writing, run chmod 600 .env. .tokens.json is created by tf auth and is already mode 0600.
- Do every step you can do yourself. Stop and ask me when a step says "Human required".
- After each step, run that step's verification check before continuing.
- tweet-factory writes drafts to files. It does not post to X. Do not post tweets for me.
- Run tf fetch on this machine only. The X refresh token rotates on every use; a second machine invalidates it.

Steps that need me (a human), which you cannot finish yourself:
- Creating an X developer app and copying the OAuth 2.0 Client ID and Client Secret.
- Clicking "Authorize app" in a browser during tf auth.
- Pasting any optional key I choose to provide (Tavily, Notion, Slack, or a direct LLM API key).

Start by installing tf (see the install page) and running `tf --help`. If you are already inside a checkout, run ./setup_x.sh --check instead and tell me what is missing.
```

The checks behind that prompt are the [setup runbook](agent.md). It is generated from `SETUP.md` in the repo so the two stay the same text.

---

Source: https://docs.tweetfactory.sh/agent.md

# Set this up for me

Give an agent the [copy-paste prompt](agent-prompt.md). The steps it must follow are below. They are `SETUP.md` from the tweet-factory repo, included verbatim at build time (headings shifted down one level so this page keeps a single title).

> **Human required.** Three moments need a person: creating the X app, clicking Authorize in the browser, and pasting any API keys. The agent does the rest.

```prompt
Set up tweet-factory on this machine for me.

Read these first, in order, and follow them:
1. https://docs.tweetfactory.sh/llms.txt
2. https://docs.tweetfactory.sh/agent.md
3. https://docs.tweetfactory.sh/install.md
4. https://docs.tweetfactory.sh/x-app.md

agent.md is the same runbook as SETUP.md in https://github.com/abhirupghosh/tweet-factory (plus this prompt). When a step and the repo disagree, trust the repo source and say so.

Rules:
- Install tf with the command in https://docs.tweetfactory.sh/install.md. Do not clone the repo unless the user already has a checkout or asked to develop from source.
- If a checkout is already on this machine, stay in it and use ./setup_x.sh. Do not delete it.
- Never invent credentials, tokens, or API keys. Never print secret values back to me.
- Write secrets only into .env. After writing, run chmod 600 .env. .tokens.json is created by tf auth and is already mode 0600.
- Do every step you can do yourself. Stop and ask me when a step says "Human required".
- After each step, run that step's verification check before continuing.
- tweet-factory writes drafts to files. It does not post to X. Do not post tweets for me.
- Run tf fetch on this machine only. The X refresh token rotates on every use; a second machine invalidates it.

Steps that need me (a human), which you cannot finish yourself:
- Creating an X developer app and copying the OAuth 2.0 Client ID and Client Secret.
- Clicking "Authorize app" in a browser during tf auth.
- Pasting any optional key I choose to provide (Tavily, Notion, Slack, or a direct LLM API key).

Start by installing tf (see the install page) and running `tf --help`. If you are already inside a checkout, run ./setup_x.sh --check instead and tell me what is missing.
```

## Runbook

> Included from [`SETUP.md`](https://github.com/abhirupghosh/tweet-factory/blob/main/SETUP.md) when this site is built. Edit that file, not a copy.

## Setting up tweet-factory for a new user — agent runbook

**Audience: a coding agent (Claude Code, Cursor, etc.) setting this up for a user on their machine.**
Follow these steps in order. Ask the user whenever you need a key, secret, or decision — never guess
or invent credentials. Keep the user in the loop; the mechanical work is a few commands plus one
browser click from them.

> The mechanical work is `install.sh` for a new machine, or `./setup_x.sh` when you are already inside a checkout (Bun/TypeScript — no Python). Your job is to
> collect the inputs, run the install that matches the machine, help the user fill their persona, and hand them the loop prompt.

### Who does what

| Step | Who |
|---|---|
| Install `tf` (script, or `./setup_x.sh` when already in a checkout), write `.env`, `chmod 600`, fetch, persona file, enrich | Agent |
| Create the X developer app and copy the OAuth 2.0 Client ID and Client Secret | **Human** |
| Click **Authorize app** in the browser during `tf auth` | **Human** |
| Paste optional keys (Tavily, Notion, Slack, direct LLM API) if they want them | **Human** |

A copy-paste prompt that points an agent at this runbook lives at
[docs.tweetfactory.sh/agent-prompt.md](https://docs.tweetfactory.sh/agent-prompt.md).

The GitHub repository is private. Release binaries are still public at `https://tweetfactory.sh/download/`. Do not treat a binary as a substitute for keeping the source private.

---

### Step 0 — Install `tf`

Prefer the release binary. It does not clone the repo:

```bash
curl -fsSL https://tweetfactory.sh/install.sh | sh
mkdir -p ~/tweet-factory && cd ~/tweet-factory
tf --help
```

The site build serves `install.sh`. The script reads `https://tweetfactory.sh/download/latest/VERSION`, then downloads `tf` and `SHA256SUMS` for that tag from `https://tweetfactory.sh/download/vX.Y.Z/`. `TF_VERSION=v0.3.0` pins a tag.

> **Verify.** `tf --help` exits 0 and prints `tweet-factory (tf)`. `command -v tf` is on `PATH`.

If this machine **already has a checkout** (a directory with `setup_x.sh` and `package.json`), stay there. Do not reinstall over it and do not delete it. Run a read-only check first — it reports missing tools and keys without changing anything:

```bash
./setup_x.sh --check
```

> **Verify.** The command exits 0 and prints a tool/key report. It must not create or edit `.env`.

A binary install has no `setup_x.sh`. Skip the check and continue with Step 1 in the data directory. `tf auth` writes `.env.example` there when it is missing.

### Step 1 — Get the user's X API credentials (REQUIRED)

The only hard requirement is an X app with **OAuth 2.0** (the sole auth X allows for reading
bookmarks). Walk the user through it, then collect the keys by asking them. Do not invent values.

> **Human required.** The user does this in a browser at https://developer.x.com/en/portal/dashboard → their app → **User authentication settings**:
>
> - App permissions: **Read**
> - Type of App: **Web App, Automated App or Bot** (confidential client → gives a refresh token)
> - Callback URI: `http://127.0.0.1:8675/callback` (must be exact)
> - Save, then open the **Keys and tokens** tab and copy the **OAuth 2.0 Client ID and Client Secret**.

`tf auth` requests these scopes: `tweet.read`, `users.read`, `like.read`, `bookmark.read`, `offline.access`.

Ask the user for:

- `TWITTER_OAUTH2_CLIENT_ID` (required)
- `TWITTER_OAUTH2_CLIENT_SECRET` (required)

Write them into `.env` (copy `.env.example` first if `.env` doesn't exist). On a binary install, `tf auth` writes `.env.example` when it is missing. Never echo secret
values back. Then lock the file down:

```bash
chmod 600 .env
```

> **Verify.** Both keys are non-empty, and the mode is `600`. This prints only `set` / `missing`, never the values:
>
> ```bash
> stat -c '%a' .env   # macOS: stat -f '%OLp' .env
> awk -F= '$1=="TWITTER_OAUTH2_CLIENT_ID"{id=$2} $1=="TWITTER_OAUTH2_CLIENT_SECRET"{sec=$2} END{if(length(id)&&length(sec)) print "oauth keys: set"; else {print "oauth keys: missing"; exit 1}}' .env
> ```

### Step 2 — Optional integrations (ask, offer to skip)

Ask, with a clear skip option. All of these can stay blank:

- `TF_LLM_PROVIDER` + a key — only if the user wants direct-API generation instead of the default Claude Code CLI backend. Default `tf generate` spawns `claude -p` and needs no key. Providers: `anthropic` (`ANTHROPIC_API_KEY`), `openrouter` (`OPENROUTER_API_KEY`), `openai` (`OPENAI_API_KEY`). Optional `TF_LLM_MODEL` overrides the model.
- `TAVILY_API_KEY` — free at https://tavily.com. Enables `tf search`, `tf enrich`, and `tf generate --timely`. Recommended.
- `NOTION_API_KEY` — internal integration at https://www.notion.so/my-integrations. The user must share pages with the integration before `tf notion` can see them.
- `SLACK_WEBHOOK_URL` — https://api.slack.com/messaging/webhooks. If set, drafts can be pushed to Slack.

> **Human required.** Pasting any of these keys. Skipping is a complete setup.
>
> **Verify.** `.env` is still mode `600`. Do not print the values.

### Step 3 — Authorize and back-fill

Once `.env` has at least the two OAuth 2.0 values:

**Checkout** ( `./setup_x.sh` is in this directory ):

```bash
NONINTERACTIVE=1 ./setup_x.sh
```

A human at the keyboard can run `./setup_x.sh` instead and let it ask for anything still blank. It installs Bun, builds `tf`, then runs the OAuth flow and the first fetch.

**Binary install** (no `setup_x.sh`):

```bash
tf auth
tf fetch
tf flush || true
```

> **Human required.** A browser opens (or a URL is printed). The user logs in as the account they want to analyze and clicks **Authorize app**. On a headless machine, pass `--no-browser` via `tf auth --no-browser` and have them open the printed URL. If the callback must be reachable from another machine, set `OAUTH_REDIRECT_URI` and `OAUTH_BIND_HOST` and register that exact callback in the X app. The default bind is `127.0.0.1`.

The first flush marks everything already in the database as processed, so `flush/pending.md` starts at 0 new items. Later runs of `tf refresh` show only what's new.

> **Verify.**
>
> ```bash
> if [ -x ./tf ]; then TF=./tf; else TF=tf; fi
> test -s .tokens.json && echo "tokens: present"
> test -s tweets.db && echo "db: present"
> "$TF" analyze
> ```
>
> `tf analyze` should print a handle and non-zero counts for the sources the account actually has. `Has refresh token: true` should have appeared in the auth output (the app needs a confidential client).

### Step 4 — Fill the persona

`setup_x.sh` does **not** write `persona/PERSONA.md`. A binary install writes `persona/PERSONA.template.md` on `tf auth` or `tf onboard` when the file is missing. Create the persona one of these ways:

- Copy the template and edit it: `cp persona/PERSONA.template.md persona/PERSONA.md`
- Or run `tf onboard` and press `f` on the forge screen. That writes `persona/PERSONA.md` from the four interview answers (what they want to be known for, a hot take, what they're building, three voice words), the account tags, and measured stats.

Make it real — this is what makes drafts sound like the user:

- Ask: their handle, the lane they want to be known for, voice rules (casing, length, tone), and any banned phrases.
- Or infer from data: `tf analyze` summarizes measured voice signals (lowercase-start rate, median length, top liked authors). Confirm the draft with the user before treating it as final.

`tf generate` still runs with no persona file: it infers from those measured signals. A filled-in `persona/PERSONA.md` is the voice source of truth.

> **Verify.** `persona/PERSONA.md` exists, and it is not still the untouched template (`@YOUR_HANDLE` should be gone). `./tf analyze` exits 0.

### Step 5 — (Optional) enrich article bookmarks

If `TAVILY_API_KEY` is set and you want full article text behind their bookmarks:

```bash
./tf enrich
```

Without that key the command errors. Skip the step when the key is absent.

> **Verify.** The command exits 0, or you skipped it because `TAVILY_API_KEY` is unset.

### Step 6 — Hand off the loop prompt

Tell the user how to generate drafts from here. For a one-off batch: `./tf generate`. In Claude Code, `/tweet-factory` runs the bundled skill, which calls `tf` for data and then drafts.

For a repeating Claude Code loop, pick based on Slack:

**With Slack:**

```
/loop 6h Spawn a subagent via the Agent tool with model "opus" to run /tweet-factory end-to-end, then post that run's drafts to Slack via ./tf notify drafts/$(date +%F).md "🧵 fresh tweet ideas". Reply with only a one-line summary. Keep going on this interval.
```

**Terminal only (no Slack):**

```
/loop 6h Spawn a subagent via the Agent tool with model "opus" to run /tweet-factory end-to-end and show me the drafts. Keep going on this interval.
```

> **Verify.** The user has a command they can run (`./tf generate`) and, if they wanted Slack, `SLACK_WEBHOOK_URL` is set. Do not run an infinite loop yourself unless they asked for one.

---

### Reminders

- **Single-host rule:** `tf fetch` (and any cron loop) must run on ONE machine only — the X refresh token rotates on every use; running it on two hosts invalidates the token.
- **Secrets never get committed:** `.env`, `.tokens.json`, `tweets.db`, `persona/PERSONA.md`, `flush/*`, `drafts/*`, and `onboarding.json` are gitignored.
- **Re-auth:** if a run logs a 401, run `./tf auth` once to mint a new token.
- **Scheduling:** `tf refresh` is the non-LLM refresh (safe to cron). `tf cron` also runs enrich, so it needs `TAVILY_API_KEY` or it errors after the fetch. `tf update` replaces a release binary and is not the database refresh. See [deploy](https://docs.tweetfactory.sh/deploy/) and the Deploy section in [`README.md`](https://github.com/abhirupghosh/tweet-factory/blob/main/README.md).
Scheduling on a server is the [deploy and cron](deploy.md) page.

---

Source: https://docs.tweetfactory.sh/install.md

# Install

Generation uses the Claude Code CLI by default, or an API key if you set one. The X app is covered in [X app setup](x-app.md).

The GitHub repository is private. The release binary is the install path for users. Source stays in the private repo.

## Fast path

```bash
curl -fsSL https://tweetfactory.sh/install.sh | sh
mkdir -p ~/tweet-factory && cd ~/tweet-factory
tf auth
```

`bun run sites:build` copies `install.sh` to the landing site as `/install.sh`. The script reads [the current tag](https://tweetfactory.sh/download/latest/VERSION), then downloads `tf-darwin-arm64`, `tf-darwin-x64`, `tf-linux-x64`, or `tf-linux-arm64` and `SHA256SUMS` from `https://tweetfactory.sh/download/vX.Y.Z/`. Those URLs redirect to a public Blob store. GitHub Release assets are not the download. Set `TF_INSTALL_DIR` to put `tf` somewhere else. Set `TF_VERSION=v0.3.0` to pin a tag.

`tf auth` writes `.env.example` when that file is not already in the directory. Copy it to `.env`, fill in the two X OAuth keys, `chmod 600 .env`, and run `tf auth` again. Then `tf fetch`.

Later, from that binary:

```bash
tf update --check
tf update
```

`tf update` compares `tf version` with the tag in `latest/VERSION`. When a newer tag is published, it downloads the matching binary, checks `SHA256SUMS`, and replaces the executable. `--check` only prints the comparison. A checkout run with `bun run src/index.ts update` refuses; pull the repo, or install the binary above.

> **Verify.** `tf --help` prints `tweet-factory (tf)` and exits 0. `command -v tf` prints the install path.

## Release assets

Built on native runners (OpenTUI’s native addon is not cross-compiled):

| Asset | Machine |
|---|---|
| `tf-darwin-arm64` | macOS Apple silicon |
| `tf-darwin-x64` | macOS Intel |
| `tf-linux-x64` | Linux x64 |
| `tf-linux-arm64` | Linux arm64 |
| `SHA256SUMS` | checksums for the four binaries |

Windows builds are not published. Check a manual download with `sha256sum -c SHA256SUMS` (macOS: `shasum -a 256 -c SHA256SUMS`).

The binary looks upward from the working directory for `tweets.db`, `.env`, or `package.json`, then falls back to the current directory. Pass `--dir` to point at a specific root.

Scoring is compiled into the binary. You do not need `X_ALGORITHM_BOOST_PLAYBOOK.md` on disk for `tf generate` to score drafts.

> **Verify.** `tf --help` lists `auth`, `fetch`, `onboard`, `generate`, `notion`, `enrich`, `flush`, `search`, `notify`, `refresh`, `update`, `cron`, and `analyze`.

## Checkout you already have

`./setup_x.sh` still installs Bun, runs `bun install`, compiles `./tf`, runs `tf auth`, then `tf fetch` and a baseline `tf flush`. Leave a working checkout in place. The installer is for machines that do not have the repo.

```bash
./setup_x.sh
```

Agents that already wrote `.env` should run `NONINTERACTIVE=1 ./setup_x.sh` so the script does not block on prompts. The browser authorize step still needs a person.

A read-only preview that changes nothing:

```bash
./setup_x.sh --check
```

Contributors run the TypeScript directly:

```bash
bun run src/index.ts --help
```

> **Verify.** `./tf --help` prints the command list. `./setup_x.sh --check` exits 0.

---

Source: https://docs.tweetfactory.sh/x-app.md

# X app setup

> **Human required.** A person creates this app in a browser. An agent cannot click through the X developer portal for you.

Bookmarks are readable only with OAuth 2.0 user context. An app-only bearer token gets a 403 on that endpoint, which is why tweet-factory dropped the old OAuth 1.0a path.

## In the developer portal

1. Open [developer.x.com](https://developer.x.com/en/portal/dashboard) and create an app (the free tier is enough for read access).
2. Under **User authentication settings** set:
   - **App permissions:** Read
   - **Type of App:** Web App, Automated App or Bot (this is a confidential client, which is what returns a refresh token)
   - **Callback URI:** `http://127.0.0.1:8675/callback`
   - Website URL: any URL you control. The CLI does not call it.
3. Save.
4. Open **Keys and tokens** and copy the **OAuth 2.0 Client ID** and **Client Secret** into `.env` as `TWITTER_OAUTH2_CLIENT_ID` and `TWITTER_OAUTH2_CLIENT_SECRET`.

The callback must match exactly, including the port `8675` and the path `/callback`. `tf auth` binds `127.0.0.1` unless you change it.

## Scopes the CLI requests

`tweet.read`, `users.read`, `like.read`, `bookmark.read`, `offline.access`.

`offline.access` is the refresh token. Without it, the access token expires and every later fetch needs a new browser login. A public client (native app) often will not return a refresh token; use the confidential web-app type and keep the client secret.

## Authorize

```bash
./tf auth
```

A browser opens. Log in as the account whose likes and bookmarks you want, and click **Authorize app**. The CLI writes `.tokens.json` (mode `0600`) and prints the granted scopes plus whether a refresh token is present.

Headless:

```bash
./tf auth --no-browser
```

Open the printed URL on a machine with a browser. The callback still has to hit the process that is waiting. From another machine, set `OAUTH_BIND_HOST` and `OAUTH_REDIRECT_URI` to a reachable URL, register that exact URI on the app, and pass the same values (`--bind`, `--redirect-uri`). The default wait is 5 minutes (`--timeout` seconds).

> **Verify.** `.tokens.json` exists, is non-empty, and the auth log said `Has refresh token: true`. File mode is `600` (`stat -c '%a' .tokens.json`).

## One machine

The refresh token rotates every time it is used. Run `tf fetch` / `tf refresh` / `tf cron` on a single machine. A second checkout that refreshes the same token invalidates the first, and the next call returns 401. Fix that with one `tf auth` on the machine you intend to keep.

> **Verify.** After auth, `./tf fetch` prints a database summary with `like`, `bookmark`, and `own` counts (a brand-new account may legitimately have zeros).

---

Source: https://docs.tweetfactory.sh/configuration.md

# Configuration

Copy `.env.example` to `.env`. The parser is lenient: blank lines and `#` comments are ignored, and the value is everything after the first `=`. `tf` loads `.env` from the project root (the nearest directory containing `tweets.db`, `.env`, or `package.json`, or the path passed to `--dir`).

After you write secrets:

```bash
chmod 600 .env
```

`tf` and `setup_x.sh` set mode `0600` when they write `.env`. A hand-edited file does not. Run `chmod 600 .env` after you edit it yourself. Never commit `.env`. Never paste values into chat.

The table below is generated from the keys in `.env.example`. Adding a key there without documenting it fails the docs build.

| Variable | Needed | What it does |
|---|---|---|
| `TWITTER_OAUTH2_CLIENT_ID` | Required | OAuth 2.0 client id from the X app’s Keys and tokens tab. |
| `TWITTER_OAUTH2_CLIENT_SECRET` | Required | OAuth 2.0 client secret. Confidential web app so the token response includes a refresh token. |
| `TF_LLM_PROVIDER` | Optional | `claude-code` (default), `anthropic`, `openrouter`, or `openai`. |
| `TF_LLM_MODEL` | Optional | Overrides the provider default. For Claude Code this is passed as `claude --model`. |
| `ANTHROPIC_API_KEY` | With provider anthropic | Direct Anthropic API. Unused when the backend is Claude Code. |
| `OPENROUTER_API_KEY` | With provider openrouter | OpenRouter key. Requests go to `https://openrouter.ai/api/v1`. |
| `OPENAI_API_KEY` | With provider openai | OpenAI key for `tf generate` when the provider is `openai`. |
| `TAVILY_API_KEY` | Optional | Timely search, article extract, `tf generate --timely`, and `tf cron` (cron calls enrich). |
| `NOTION_API_KEY` | Optional | Internal integration secret. Pages must be shared with the integration. |
| `SLACK_WEBHOOK_URL` | Optional | Incoming webhook for `tf notify`, `--post-to-slack`, and the cron pending ping. |
| `TF_LICENSE_KEY` | Optional | License key for paid features. The default build allows every feature and does not send the key. |
| `TF_API_ORIGIN` | Optional | Entitlement API origin once a billing provider is linked. Default `https://tweetfactory.sh`. |
| `TF_CLOUD_ORIGIN` | Optional | Cloud sync API origin. Default `https://tweetfactory.sh`. Nothing is uploaded until `tf login` and `tf sync push`. |
| `OAUTH_REDIRECT_URI` | Optional | Defaults to `http://127.0.0.1:8675/callback`. Must be registered on the X app. |
| `OAUTH_PORT` | Optional | Callback listen port. Default `8675`. |
| `OAUTH_BIND_HOST` | Optional | Callback bind address. Default `127.0.0.1`. Widen only for cross-machine auth. |
## Project root

Global flag on every command:

```bash
tf --dir /path/to/checkout fetch
```

Without `--dir`, `tf` walks up to six directories from the working directory looking for `tweets.db`, `.env`, or `package.json`.

## What stays out of git

`.env`, `.tokens.json`, `.cloud.json`, `tweets.db`, `persona/PERSONA.md`, `flush/*` (except `.gitkeep`), `drafts/*` (except `.gitkeep`), `onboarding.json`, `logs/`, `backups/`. `.cloud.json` appears only after `tf login`.

> **Verify.** `git check-ignore -v .env .tokens.json .cloud.json tweets.db persona/PERSONA.md` prints a matching ignore rule for each path that exists. `stat` shows mode `600` on `.env` and `.tokens.json`. After `tf login`, `.cloud.json` is mode `600` too.

---

Source: https://docs.tweetfactory.sh/commands.md

# Commands

```
tf <command> [options]
tweet-factory <command>   # same program, via the package bin
```

`tf --help`, `tf -h`, and `tf help` print the short list and exit 0. `tf --version`, `tf -v`, and `tf version` print `tf <version>` and exit 0. An unknown command prints the help and exits 2.

Every command accepts `--dir <path>` (see [Configuration](configuration.md)). This page is checked against the command table in `src/cli.ts` when the docs build: a new command that is missing here fails the build.

## tf auth

OAuth 2.0 PKCE. Writes `.tokens.json`.

```bash
tf auth [--port N] [--bind HOST] [--redirect-uri URI] [--no-browser] [--timeout SECS]
```

| Flag | Default |
|---|---|
| `--port` | `OAUTH_PORT` or `8675` |
| `--bind` | `OAUTH_BIND_HOST` or `127.0.0.1` |
| `--redirect-uri` | `OAUTH_REDIRECT_URI` or `http://127.0.0.1:<port>/callback` |
| `--no-browser` | off; when set, the URL is printed and no browser is launched |
| `--timeout` | `300` seconds |

Scopes: `tweet.read`, `users.read`, `like.read`, `bookmark.read`, `offline.access`. Details and the human click are in [X app setup](x-app.md).

> **Human required.** Someone clicks **Authorize app** in a browser.
>
> **Verify.** `.tokens.json` exists and the log includes `Has refresh token: true`.

## tf fetch

Pull likes, bookmarks, and your posts into `tweets.db`.

```bash
tf fetch [like|bookmark|own] [--incremental]
```

With no source words, it fetches all three. User id comes from `/2/users/me`. Pages are 100 tweets, with a one-second pause between pages. A 401 refreshes the access token and retries. A 403 skips that source. A 429 sleeps until the rate-limit reset.

`--incremental` stops a source early once a page contains no ids that are already stored. The first pull should be a full fetch (no flag). `tf refresh` and `tf cron` always fetch incrementally.

> **Verify.** The log ends with a database summary: counts for `like`, `bookmark`, `own`, and distinct authors. `test -s tweets.db`.

## tf onboard

OpenTUI onboarding. Needs a terminal.

```bash
tf onboard [--selftest]
```

Screens, in order: welcome, four interview questions, account tagging, a heuristic roast, forge, optional Notion, generate.

Interview questions:

1. What do you want to be known for, in one breath?
2. Your hottest take that's gotten you in trouble?
3. What are you building right now?
4. Describe your voice in 3 words.

Account tags, cycled with space: (none), `inspiration`, `competitor`, `north-star`, `friend`. Arrow keys move. Enter continues.

The roast uses the same per-head scorer as `tf generate`: editorial strengths times the published action weights. It does not apply account calibration. `tf analyze` prints whether your own history is thick enough to calibrate.

On the forge screen, `f` writes `persona/PERSONA.md`. `n` opens Notion search. `g` generates drafts with your LLM. `q` quits.

`--selftest` renders one frame and exits. It still starts the TUI renderer, so it needs an environment where `tf onboard` can open.

> **Verify.** After forge, `persona/PERSONA.md` exists and names the handle `tf analyze` prints.

## tf generate

Draft tweets with your LLM. Writes `drafts/YYYY-MM-DD.md` and `onboarding.json`.

```bash
tf generate [--n N] [--timely] [--post-to-slack] [--provider NAME] [--model NAME] [--json] [--no-style-check]
```

| Flag | Effect |
|---|---|
| `--n` | How many ideas to ask for. Default `4`. Each idea is 2–3 variants. |
| `--timely` | One Tavily news search is added to the prompt when `TAVILY_API_KEY` is set. The query is `AI agents coding startups` when your posts hit the analyzer’s energy-marker list, otherwise `technology`. For a query you choose, run `tf search` yourself. |
| `--post-to-slack` | After writing the file, post it with `tf notify`. |
| `--provider` | Overrides `TF_LLM_PROVIDER` for this run. |
| `--model` | Overrides `TF_LLM_MODEL` for this run. |
| `--json` | Print the bundle on stdout instead of writing the markdown file. `onboarding.json` is still written. |
| `--no-style-check` | Skip the [style check](#style-check). The prompt's style rules are dropped too. |

The model is asked for one JSON object: persona summary, content pillars, reply targets, cadence, strategy, `ideas` (each with 2–3 variants), and a flat `drafts` array. The model’s `score` field is ignored. After Zod validates the JSON, tweet-factory scores every variant locally: copy-link share, reply (20 on an original a mutual would see, 5 otherwise), DM share, quote, follow, repost, like, and the negative heads report, mute, not-interested, and block. The markdown file shows that breakdown, the weighted total, and a 0–100 score. A note at the top says to post one variant per idea, because a second post from you in one viewer’s pool is multiplied by 0.625 and DPP separates near-duplicates.

When `tweets.db` has at least 8 of your own posts with impressions, reply, quote, repost, and like rates (per impression, per format) scale those four strengths. Bookmarks are printed as a diagnostic and do not scale a head. Fewer than 8 impressed posts leaves the scales at 1 and says the history is thin. Posts older than 48 hours are preferred when 8 of them exist.

Context sent as fenced reference data (not as instructions): `flush/pending.md` when it has new items, a few recent posts, tagged Notion pages (about 6,000 characters), the calibration block, and the optional Tavily blurb. The system prompt is your persona plus measured stats plus the ranking prompt built from `src/rank/weights.ts`.

Default backend and keys: [LLM providers](llm.md).

Every variant goes through the [style check](#style-check) before it is scored, so the score in the file is the score of the text in the file. A variant the check touched shows a `Style check:` block with each fix and any flags left, and the score before fixes. In `--json` and `onboarding.json`, each variant carries `style: { fixes, flags, original?, originalScore? }`. stderr ends with a one-line count.

> **Verify.** `drafts/<today>.md` contains a `| Head |` table and `Post one variant`, and `onboarding.json` parses as JSON with a `drafts` array. `--json` prints that object and exits 0.

## tf brain-dump

Turn raw dictation into an outline with notes and 2–3 scored angles, before full drafting. Same LLM, persona, and scorer as `tf generate`.

```bash
tf brain-dump "rough thoughts, pasted or dictated"
tf brain-dump --file memo.txt
pbpaste | tf brain-dump -
tf brain-dump --file memo.txt --draft 2
tf brain-dump [<text> | --file PATH | -] [--angles 2|3] [--draft N] [--json] [--provider NAME] [--model NAME] [--no-style-check]
```

| Flag | Effect |
|---|---|
| `<text>` | Dictation as a quoted argument. |
| `--file`, `-f` | Read the dictation from a file, such as a voice-memo transcript. |
| `-` | Read stdin. Piped input is read without the dash. |
| `--angles` | How many distinct angles to ask for, clamped to 2–3. Default `3`. |
| `--draft N` | After printing, feed angle `N` into the `tf generate` flow. That writes `drafts/YYYY-MM-DD.md` and `onboarding.json` like `tf generate`. |
| `--json` | Print the outline and scored angles as JSON. |
| `--provider`, `--model` | Override `TF_LLM_PROVIDER` and `TF_LLM_MODEL` for this run. |
| `--no-style-check` | Skip the [style check](#style-check) on the angles and on `--draft` drafts. |

Output is a one-line summary, a numbered outline where each point can carry notes (your own words worth keeping, gaps), and the angles. Each angle is one tweet in your voice with its aim and a 0–100 score from the same per-head scorer as `tf generate`; the model's own scores are ignored. Angles go through the [style check](#style-check) first, and any fixes or flags print under the angle. Nothing is written to disk unless you pass `--draft`. No input exits 2.

The dictation is sent to your LLM as fenced reference data, not instructions, and is cut at 20,000 characters. Persona loading and backends are the same as `tf generate` ([LLM providers](llm.md)).

> **Verify.** `tf brain-dump --help` prints usage. With a configured LLM, `tf brain-dump "a rough thought"` prints `## Outline` and `### Angle 1`.

## tf lint

Run the style check on one draft without an LLM. Fixed text goes to stdout and the report to stderr, so it pipes.

```bash
tf lint "Here's the thing — agents need memory"
pbpaste | tf lint -
tf lint --file draft.txt --json --score
tf lint [<text> | --file PATH | -] [--json] [--no-fix] [--strict] [--score]
```

| Flag | Effect |
|---|---|
| `<text>`, `--file`, `-` | The draft: a quoted argument, a file, or stdin. |
| `--no-fix` | Leave the text alone and report every rewrite as a flag. |
| `--strict` | Exit 1 when a flag remains. |
| `--score` | Add the 0–100 score before and after fixes (uncalibrated). |
| `--json` | Print `{ text, original, changed, fixes, flags }` (plus `score`, `originalScore` with `--score`). |

```text
$ tf lint "Here's the thing — agents need memory. Fast. Cheap. Reliable."
Agents need memory. Fast. Cheap. Reliable.

fixed (heres-the-thing): "Here's the thing — agents need" -> "Agents need"
flag (triad): stacked rhetorical triad reads as AI; keep the one that matters: "Fast. Cheap. Reliable."
```

No input exits 2.

### Style check

Inspired by Theo's `noEmDashCopy` lint rule. It runs on every draft `tf generate` and `tf brain-dump` produce (and on the generate screen in `tf onboard`), before the draft is scored or shown. The same rules are listed in the generation prompt so the model avoids them in the first place. The tweetfactory.sh score page runs the same check and offers the rewrite.

Rewritten, with deterministic rules:

| Pattern | Rewrite |
|---|---|
| `X — and/but/so/which …` | comma |
| `X — it's / we / the / 3 …` (a new clause) | period, capitalized unless the draft is all lowercase |
| `X — short tail.` (4 words or fewer) | colon |
| `X — aside — Y` | parentheses |
| dash before a line break / at the end / as a bullet | colon / `...` / `- ` |
| anything else with an em dash, a spaced en dash, or ` -- ` | comma |
| `pre–seed` (en dash between letters) | hyphen |
| `delve into` (any tense) | `dig into` |
| leading `Here's the thing` / `In today's fast-paced world,` | dropped |

Kept as is: number ranges such as `2023–2026` and `2–3`, inline code, fenced code, and URLs.

Flagged, not rewritten: `delve`, `tapestry`, `testament to`, `game-changer`, `unleash` / `unlock the potential`, `it's not X, it's Y` and `X isn't Y, it's Z`, `not just X, but Y`, leading `In a world where`, `let's dive in`, `ever-evolving landscape`, three or more one- or two-word sentences in a row or `no X, no Y, no Z`, more than 2 emoji, more than 1 hashtag.

The list is one data file, `src/style/tells.ts`. Each entry is a regex, an optional replacement, a message, and the phrase the prompt names. Add a replacement only when it is safe in every sentence the pattern can match.

> **Verify.** `tf lint "we shipped — and nobody cared"` prints `we shipped, and nobody cared` and exits 0. `tf lint --strict "a game-changer"` exits 1.

## tf notion

Tag Notion pages as grounding for generation. Requires `NOTION_API_KEY`, and the pages must be shared with the integration.

```bash
tf notion search [query] [--json]
tf notion tag <pageId> --tag <label> [--note <text>]
tf notion untag <pageId>
tf notion list [--json] [--full]
tf notion sync [--force]
```

`search` lists pages the integration can see. `tag` stores the page (markdown body included) in `tweets.db` under your freeform label. `list` prints tags and titles; `--full` with `--json` includes cached content. `sync` refreshes tagged pages whose `last_edited` changed. `--force` refreshes all of them. `tf cron` calls `sync` when `NOTION_API_KEY` is set.

> **Verify.** `tf notion list` shows the page you tagged. A later `tf generate` can quote the tag only as background; it is instructed not to paste the page verbatim.

## tf enrich

Pull article text for URLs on stored tweets. Requires `TAVILY_API_KEY`.

```bash
tf enrich [--all] [--force]
```

Default source is bookmarks only. `--all` also scans likes and your own posts. X article URLs (`x.com/i/article/…` or `twitter.com/i/article/…`) are read through the X API. Other URLs go through Tavily Extract. `t.co` links are skipped. Results are cached in `article_content`; `--force` refetches.

> **Verify.** The log reports extract or x-article counts, and the command exits 0.

## tf flush

Show interactions that are not yet marked processed.

```bash
tf flush [--commit] [--status] [--count]
```

| Flag | Effect |
|---|---|
| (none) | Write `flush/pending.md`. The first run baselines: every current row is marked processed and the pending total is 0. |
| `--commit` | Mark the current pending ids processed, and move `pending.md` to `flush/archive/`. |
| `--status` | Print pending counts to stderr. |
| `--count` | Print a single integer to stdout. `tf cron` uses this. |

Sections in the file: `NEW LIKES`, `NEW BOOKMARKS`, `YOUR NEW TWEETS`.

> **Verify.** After the first `tf flush` on a fresh database, the file contains `Total pending: 0`. After a later incremental fetch of new posts, a second `tf flush` lists them.

## tf search

Tavily web search. Requires `TAVILY_API_KEY`.

```bash
tf search "query words" [--news] [--days N] [--max N] [--json]
```

Without `--news` the topic is general. With `--news`, the topic is news and `--days` (default 7) limits the window. `--max` defaults to 5. Human output is a short markdown list; `--json` is the raw response.

> **Verify.** The command prints a `## Tavily:` heading, or JSON with `--json`.

## tf notify

Post a file to Slack in chunks of about 3,500 characters. Requires `SLACK_WEBHOOK_URL`. If the webhook is unset, it logs a skip and returns.

```bash
tf notify <file> [header]
```

The default header inside the library is `🧵 Fresh tweet drafts ready`. The argument replaces it.

> **Verify.** The log says `posted to Slack`, and the channel shows the file. With no webhook, the log says `SLACK_WEBHOOK_URL not set`.

## tf refresh

Incremental fetch, then rebuild `flush/pending.md`. Does not call an LLM, Tavily, Notion, or Slack.

```bash
tf refresh
```

`update.sh` in the repo is a thin wrapper around this. This is the command to schedule when you have no Tavily key. It used to be `tf update`. `tf update` now replaces a release binary.

> **Verify.** The log shows `Fetch mode: incremental` and a `pending written` line (or a baseline line on the very first flush).

## tf cron

Server-loop entrypoint used by `cron_run.sh`.

```bash
tf cron [--enrich-all]
```

Order: incremental fetch, enrich, Notion sync if `NOTION_API_KEY` is set, flush rebuild, then a Slack ping when the pending count is greater than 0 and `SLACK_WEBHOOK_URL` is set. The Slack text tells you to run `tf generate`. It does not generate drafts.

`--enrich-all` passes `--all` through to enrich (likes and your own posts, not only bookmarks).

Enrich throws if `TAVILY_API_KEY` is missing, and that happens after the fetch. Without Tavily, schedule `tf refresh` instead.

> **Verify.** The stderr log contains `===== cron` and `pending=<n>`. With new items and a webhook, it also contains `slack pinged`.

## tf analyze

Voice and taste stats from `tweets.db`. No network.

```bash
tf analyze [--json] [--roast]
```

Default output: handle, counts of your tweets / likes / bookmarks, percent of posts that start lowercase, median word count, up to three energy phrases from a fixed list, and the ten authors you have liked most.

`--json` prints the same stats as JSON, including six recent original posts. `--roast` scores those recent posts with the per-head scorer and a one-line quip, and prints whether account calibration has enough history. The human-readable summary includes that calibration line too.

> **Verify.** `tf analyze --json` prints JSON with `handle`, `n_own`, `n_likes`, and `n_bookmarks`.

## tf login

Link this checkout to a tweetfactory.sh account. Does not upload tweets, the persona, or drafts.

```bash
tf login [--origin URL]
```

Prints a device code and a verification URL. Approve it at [tweetfactory.sh/account](https://tweetfactory.sh/account/) while signed in with X. On success, writes `.cloud.json` mode `0600`.

`--origin` overrides `TF_CLOUD_ORIGIN` for this run. The default origin is `https://tweetfactory.sh`.

> **Human required.** Someone signs in on tweetfactory.sh and approves the code.
>
> **Verify.** `.cloud.json` exists, mode `600`. The log says nothing is uploaded until `tf sync push`. See [Cloud sync](cloud-sync.md).

## tf sync

Optional cloud copy of `tweets.db`, `persona/PERSONA.md`, `drafts/*.md`, and Notion tags. Requires `tf login` first, except `status` with no link, which only prints that the checkout is not linked.

```bash
tf sync push
tf sync pull [--replace]
tf sync status [--json]
tf sync delete --yes
```

| Subcommand | Effect |
|---|---|
| `push` | Upload a full snapshot. Replaces the previous remote snapshot on commit. |
| `pull` | Download into the local database and files. Keeps a local file newer than the remote copy. |
| `pull --replace` | Clear local sync tables first, then drop local persona or draft files the remote snapshot lacks. |
| `status` | Bytes, rows, quota, and counts. `--json` prints the status object. |
| `delete --yes` | Delete the remote copy. Local files stay. Without `--yes` the command refuses. |

`tf sync --help` prints the subcommands and exits 0.

> **Verify.** `tf sync status` before login says the checkout is not linked. After a push, the same command prints a byte quota. `tf sync delete` without `--yes` exits with an error and leaves the remote copy.

## tf update

Replace this release binary with the latest one published at tweetfactory.sh.

```bash
tf update
tf update --check
```

The command reads the current tag from [https://tweetfactory.sh/download/latest/VERSION](https://tweetfactory.sh/download/latest/VERSION) and compares it with the version compiled into this binary (`tf version`). When the published tag is newer, it downloads `tf-darwin-arm64`, `tf-darwin-x64`, `tf-linux-x64`, or `tf-linux-arm64` for this machine from `https://tweetfactory.sh/download/vX.Y.Z/`, checks that file against `SHA256SUMS`, and replaces the running executable. The new bytes are written beside the current binary, marked executable, then renamed into place. Those URLs redirect to a public Blob store.

When this binary is already that tag, the command prints that it is up to date and does not download. A binary newer than the published tag is left in place. `--check` prints the comparison and does not download or replace anything.

A dev build (`bun run src/index.ts`, or a binary compiled without a release tag) refuses and points at [install.sh](https://tweetfactory.sh/install.sh). If the install directory is not writable, the command exits with a permission error and leaves the current binary in place.

The database refresh is `tf refresh`, not `tf update`.

> **Verify.** `tf update --check` on a release binary prints either `up to date` or `is available` and exits 0. `bun run src/index.ts update` exits non-zero and mentions `install.sh`.

## tf version

Print the version and exit 0.

```bash
tf version
tf --version
tf -v
```

A release binary prints the tag it was compiled from, such as `tf v0.3.0`. Running from a checkout prints the `package.json` version with `-dev` appended, such as `tf 0.3.1-dev`.

> **Verify.** `tf version` prints a single line starting with `tf ` and exits 0. `tf --help` lists `version`.

---

Source: https://docs.tweetfactory.sh/cloud-sync.md

# Cloud sync

Local files are the default. `tf` does not upload anything until you run `tf login` and then `tf sync push`. Skip both commands and the checkout never contacts tweetfactory.sh.

The copy lives on the [tweetfactory.sh](https://tweetfactory.sh) account you sign into with X. The account page at [/account/](https://tweetfactory.sh/account/) shows the synced persona and drafts, and it can export or delete that copy.

## Link a checkout

```bash
tf login
```

`tf login` starts a device-code flow. It prints a short code (`ABCD-EFGH`) and a URL such as `https://tweetfactory.sh/account/?code=ABCD-EFGH`. Open that URL in a browser where you are signed in with X, approve the code, and return to the terminal. The CLI writes `.cloud.json` (mode `0600`) and stops. No tweets, persona, or drafts are sent by login.

The code expires in about 10 minutes. The saved link lasts about 90 days. Run `tf login` again when it expires.

Origin, first match wins: `--origin`, then `TF_CLOUD_ORIGIN`, then the origin already stored in `.cloud.json`, then `https://tweetfactory.sh`.

## Push, pull, status, delete

```bash
tf sync push
tf sync pull
tf sync pull --replace
tf sync status
tf sync status --json
tf sync delete --yes
```

`push` uploads the current local snapshot:

- `tweets.db` rows: authors, tweets (likes, bookmarks, your posts, metrics), article text, Notion tags
- `persona/PERSONA.md`
- `drafts/*.md`

A push replaces the previous remote snapshot. An empty checkout still commits, which clears the remote copy. The previous snapshot stays until the commit succeeds. A push that exceeds the quota is rejected and leaves the last successful snapshot in place.

`pull` writes remote rows into the local database and writes persona and draft files. A local file newer than the remote copy is kept. `pull --replace` clears local sync tables first and deletes local persona or draft files the remote snapshot does not contain.

`status` prints bytes stored, row counts, and the quota. With no `.cloud.json` it prints that the checkout is not linked. `delete --yes` removes the remote copy and the device token. It does not delete local files and it does not delete the X sign-in on tweetfactory.sh.

> **Verify.** After `tf login`, `test -f .cloud.json` and `stat -c '%a' .cloud.json` is `600`. `tf sync status` prints a quota line only after a push. `git check-ignore -v .cloud.json` matches an ignore rule.

## What is encrypted

Encryption is server-side AES-GCM with `SYNC_ENCRYPTION_KEY`. It is not end-to-end: the operator who holds that key can decrypt. Losing the key makes stored ciphertext unreadable. The key is separate from `SESSION_SECRET`.

Encrypted before write: tweet text, author descriptions, article extracts, Notion notes and page text, persona bodies, and draft bodies. Device tokens are stored as SHA-256 hashes. The access token itself is sealed only until the CLI polls it once.

Left queryable: ids, usernames, public metrics, Notion tags, and filenames. The account page lists drafts by filename and shows persona and draft text after the server decrypts them for the signed-in user.

Rows are keyed by the X user id from the device token or the session. A request cannot name another user’s id.

## Storage

Structured rows go to Postgres (`DATABASE_URL`, Neon or PlanetScale). That holds authors, tweets, articles, Notion pages, device codes, token hashes, and a per-user usage row. Postgres fits relational keys, a generation-scoped replace, and a byte/row quota checked inside the write transaction.

Persona and draft files go to Vercel Blob (`BLOB_READ_WRITE_TOKEN`) as private ciphertext. Those bodies are files, not rows you filter in SQL.

Upstash Redis still works for sign-in sessions when `DATABASE_URL` is unset. Cloud sync refuses to start without Postgres, a Blob token, and `SYNC_ENCRYPTION_KEY`. Redis is a poor fit for tens of thousands of tweet rows.

The usage table `tf_sync_usage` records `bytes_stored`, `rows_synced`, last push, and last pull. Nullable `quota_bytes` and `quota_rows` columns exist so a later billing change can override the env quota per user. This release does not write those columns.

Default quota: 50 MiB (`52428800` bytes) and 50,000 rows. Optional env `SYNC_QUOTA_BYTES` and `SYNC_QUOTA_ROWS` raise or lower that ceiling (caps at 5,000,000,000 bytes and 5,000,000 rows). A push over the quota returns HTTP 402 and stores nothing from that attempt.

## Account page

While signed in at [tweetfactory.sh/account](https://tweetfactory.sh/account/):

- Approve the code from `tf login`.
- Read the synced persona and drafts.
- **Export** downloads `tweetfactory-sync.json` (the committed snapshot). Very large libraries return an error instead of a truncated file.
- **Delete synced data** removes the cloud copy and device tokens. The X session remains. Local files on your machine stay.

**Delete account** on the score page removes the session, saved score drafts, and the synced copy when sync is configured. `tf sync delete` does not do that.

Provisioning for the site owner is in the repository `web/README.md`. The CLI only needs `TF_CLOUD_ORIGIN` when the API is not `https://tweetfactory.sh`.

---

Source: https://docs.tweetfactory.sh/persona.md

# Persona

`persona/PERSONA.md` is the voice source of truth. `tf generate` puts the whole file in the system prompt and tells the model to match casing, length, phrasing, and stance. The filled-in file is gitignored. The committed template is `persona/PERSONA.template.md`.

## Create it

Two paths:

```bash
cp persona/PERSONA.template.md persona/PERSONA.md
```

Edit identity, voice rules, banned phrases, and the lane (the template suggests staying about 80% on one or two topics).

Or run `tf onboard`, answer the four questions, tag accounts, and press `f` on the forge screen. That writes a persona from:

- the interview answers (lane, hot take, what you’re building, three voice words)
- tags you set on accounts (`inspiration`, `competitor`, `north-star`, `friend`)
- measured stats: lowercase-start rate, median word count, energy markers

`setup_x.sh` does not create this file. See the [runbook](agent.md).

## What the template contains

Identity, voice rules, lane, post shapes that perform, patterns to avoid, taste signals (who you engage with), a short algorithm-prior note, and a running-notes section. The optional Claude Code skill (`/tweet-factory`) appends dated notes there from `flush/pending.md`. The `tf` binary does not edit the persona on its own after forge.

## Measured signals

`tf analyze` reads `tweets.db` and reports:

- how many of your original posts start with a lowercase letter
- the median word count of those posts
- which of a fixed phrase list show up most (examples: `cooked`, `bullish`, `wild`)
- the authors you like most often

`tf generate` includes those numbers even when `PERSONA.md` is missing, and says so in the prompt (“infer voice from the measured signals”). A written persona still wins when both exist.

## Flush

`tf flush` (also run by `tf refresh` and `tf cron`) writes `flush/pending.md`: new likes, bookmarks, and your new posts since the last `--commit`. The first flush on a database baselines everything currently stored, so the pending total is 0 until something new is fetched.

The Claude skill uses that file to update the persona. `tf generate` includes the pending file in the user prompt when the total is not zero, capped around 4,000 characters, inside a reference-data fence.

> **Verify.** `persona/PERSONA.md` does not still say `@YOUR_HANDLE`. `tf analyze` and the Identity section name the same person. `tf flush --status` runs without error.

---

Source: https://docs.tweetfactory.sh/llm.md

# LLM providers

`tf generate` and the generate screen inside `tf onboard` call one backend. The default is the Claude Code CLI. No API key.

Set the backend in `.env` or pass `--provider` / `--model` for a single run.

| `TF_LLM_PROVIDER` | Key | Default model |
|---|---|---|
| `claude-code` (default) | none; uses your `claude` login | the CLI’s own default. `TF_LLM_MODEL` is passed as `claude --model` |
| `anthropic` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` |
| `openrouter` | `OPENROUTER_API_KEY` | `anthropic/claude-sonnet-4.6` |
| `openai` | `OPENAI_API_KEY` | `gpt-4o` |

```bash
# one-off, without editing .env
tf generate --provider anthropic --model claude-sonnet-4-6
```

Direct API calls use temperature `0.8` and a token cap (8,000 for a full bundle, so four ideas with two or three variants fit). Claude Code gets a 240 second timeout.

## Claude Code subprocess

`tf` runs:

```
claude -p <prompt> --output-format json --permission-mode dontAsk --tools "" --disallowedTools "*,mcp__*" --strict-mcp-config --max-turns 1 --no-session-persistence
```

`--tools ""` removes built-in tools. `--allowedTools` only pre-approves tools, so it is not used as the control. Scraped tweets, articles, and Notion pages sit inside `<reference_data>`, and a closing fence typed inside that text is stripped. The subprocess cannot run shell commands or edit files.

If `claude` is not on `PATH`, the error tells you to install Claude Code or set `TF_LLM_PROVIDER` and a key.

Claude Code has to be logged in on that machine, including a server you cron from. `tf` does not ship a Claude credential.

## Output shape

The model must return one JSON object. Zod checks `persona` (handle, identity, lane, voice rules, hottest take, building), `contentPillars`, `replyTargets`, `cadence`, `strategy`, and either `ideas[]` (each with `variants[]` of `text`, optional `aim` and `note`) or a legacy `drafts[]`. A flat `drafts` array is always written back after scoring, with `text`, `score`, `signal`, and optional `note`. Prose or a broken object throws. Re-run, or switch model.

Scores are computed in-process after the model returns text. tweet-factory does not execute the X ranking code. It multiplies editorial strengths by the published weights in `src/rank/weights.ts` (x-algorithm `cb45b55`). The same module builds the system prompt, so the prompt and the scorer share one table. The narrative write-up is `X_ALGORITHM_BOOST_PLAYBOOK.md`. When your own posts have enough impressions, `src/rank/calibrate.ts` scales reply, quote, repost, and like strengths from `tweets.db`. Bookmarks stay diagnostic. The formula is on [how drafts are scored](how-tweet-factory-scores-drafts.md).

An optional org skill at `~/.claude/skills/twitter-algorithm-optimizer/` can replace that playbook when a person runs the `/tweet-factory` Claude Code skill. `tf generate` always uses the weights compiled into the binary.

> **Verify.** `tf generate --n 1 --json` prints a JSON object with a `drafts` array, or fails with a clear provider error (missing `claude`, missing API key). Fix that error before treating generation as set up.

---

Source: https://docs.tweetfactory.sh/integrations.md

# Tavily, Notion, and Slack

All three are optional. A setup with only X credentials and an LLM still fetches, builds a persona, and generates drafts.

## Tavily

Key: `TAVILY_API_KEY` from [tavily.com](https://tavily.com).

| Command | What it calls |
|---|---|
| `tf search` | Tavily Search. `--news` switches the topic to news. |
| `tf enrich` | Tavily Extract for ordinary URLs. X-hosted articles use the X API instead. |
| `tf generate --timely` | One news search, last 7 days, 5 results, folded into the prompt. |
| `tf cron` | Calls enrich. Without the key, cron errors after the fetch. Use `tf refresh` instead. |

Search defaults: general topic, 5 results, basic depth, an answer summary included. News searches default to 7 days.

> **Human required.** Creating the Tavily account and pasting the key.
>
> **Verify.** `tf search "tweet-factory" --max 1` prints a result list.

## Notion

Key: `NOTION_API_KEY`, an internal integration secret from [notion.so/my-integrations](https://www.notion.so/my-integrations).

> **Human required.** Create the integration, copy the secret, and share each page or database with the integration. Unshared pages are invisible. `tf notion search` only returns what that share allows.

Commands are `search`, `tag`, `untag`, `list`, and `sync`. See [Commands](commands.md#tf-notion). The onboarding TUI can search and tag too (`n` on the forge screen).

Tagged pages are stored in `tweets.db` with your label and an optional note. `tf generate` includes them as reference material (roughly 1,500 characters per page, 6,000 overall) and is told to use the tag as a hint — voice, product facts, or idea seeds — rather than quoting the page. `tf cron` syncs pages whose last-edited time changed.

> **Verify.** `tf notion search` lists at least the pages you shared. `tf notion tag <id> --tag voice` then `tf notion list` shows that tag.

## Slack

Key: `SLACK_WEBHOOK_URL`, an [incoming webhook](https://api.slack.com/messaging/webhooks).

| Path | Behavior |
|---|---|
| `tf notify <file> [header]` | Posts the file, split around 3,500 characters, as webhook text. |
| `tf generate --post-to-slack` | Writes the drafts file, then notifies. |
| `tf cron` | If the pending count is above zero, posts a one-line ping telling you to run `tf generate`. It does not attach drafts. |

No webhook: `tf notify` logs a skip and returns. Cron stays quiet.

> **Human required.** Create the webhook in Slack and paste the URL.
>
> **Verify.** `printf 'hello from tf\n' > /tmp/tf-slack.txt && tf notify /tmp/tf-slack.txt "tf setup check"` posts that one line. Delete the Slack message if the channel is shared.

---

Source: https://docs.tweetfactory.sh/deploy.md

# Deploy and cron

These scripts live in the repo root. They are a reference loop for a machine that already has a checkout, not a hosted service, and not the path for a new install (that is [Install](install.md)). Personal files (`tweets.db`, `persona/PERSONA.md`, `.env`, `.tokens.json`) stay on that machine. `deploy.sh` recompiles `./tf` with the same flags as `bun run build`.

Run fetch on one host only. The X refresh token rotates on use.

## What each script does

| Script | Does |
|---|---|
| `update.sh` | `tf refresh`: incremental fetch and a flush rebuild. No LLM, no Tavily. |
| `cron_run.sh` | `tf cron`: incremental fetch, enrich, Notion sync when a key is set, flush, Slack ping if anything is pending. Prefers `./tf`, otherwise `bun run src/index.ts cron`. Logs to `logs/cron.log`. |
| `deploy.sh` | `git pull --ff-only`, `bun install --frozen-lockfile`, recompile `./tf`. Does not touch gitignored state. Log: `logs/deploy.log`. |
| `backup.sh` | Copies `tweets.db` and `persona/PERSONA.md` into `backups/`, keeps 7 daily snapshots, pushes nothing. Log: `logs/backup.log`. |

`tf cron` calls enrich, and enrich requires `TAVILY_API_KEY`. Without that key, cron fails after the fetch. Schedule `update.sh` (or `tf refresh`) instead until Tavily is configured. `tf update` replaces a release binary; it does not refresh `tweets.db`.

`tf cron` does not call `tf generate`. Generation stays something you run, or a separate agent loop, because it spends LLM time and should be read before anything is posted.

## Cron

Paths below are the checkout. Use a user crontab on the same account that owns `.tokens.json`.

```bash
# hourly refresh without an LLM
0 * * * * /path/to/tweet-factory/update.sh

# or, when TAVILY_API_KEY is set: fetch + enrich + flush + slack ping
# 0 * * * * /path/to/tweet-factory/cron_run.sh

# nightly local snapshots
15 3 * * * /path/to/tweet-factory/backup.sh
```

`cron_run.sh` and `deploy.sh` expect `bun` on `PATH` or at `$HOME/.bun/bin`.

A systemd timer can call the same scripts. The repo does not ship a unit file.

## Updating the code

```bash
./deploy.sh
```

Safe to run at the start of a loop. It fast-forwards `origin/main` only. If you have local commits, the pull fails and the script keeps the current checkout (it logs a warning).

## Backups

`backups/` is gitignored. Snapshots are named `tweets-YYYY-MM-DD.db` and `PERSONA-YYYY-MM-DD.md`. Keep that directory off any public remote. The script keeps the newest 7 of each.

> **Verify.** `./tf refresh` exits 0 on the server. `logs/cron.log` or the `tf refresh` output shows `Fetch mode: incremental`. `./backup.sh` then `ls backups` shows today’s snapshot when `tweets.db` exists. `git status` does not list `.env`, `.tokens.json`, or `tweets.db`.

---

Source: https://docs.tweetfactory.sh/security.md

# Security

tweet-factory stores another person’s posts (everything you liked or bookmarked) plus your own, and it holds a long-lived X refresh token. Treat the checkout like a credential.

## Secrets

- `.env`, `.tokens.json`, and `.cloud.json` are gitignored.
- `.tokens.json` and `.cloud.json` are written atomically, mode `0600`.
- When `tf` updates `.env`, and when `setup_x.sh` writes keys, the file is mode `0600`. A hand-edited `.env` is not. Run `chmod 600 .env` after editing it yourself. `.env.tmp` and `.tokens.json.tmp` are gitignored.
- Opening `tweets.db` for write sets it to mode `0600`, including an existing file that was looser. `backup.sh` sets mode `0600` on each snapshot of `tweets.db` and `persona/PERSONA.md`.
- Do not log token or key values. The docs’ verification commands print `set` or `missing`, not the secret. X token and API errors log the status code only.
- `backups/` contains the database and the persona. It is local on purpose. Do not point it at a public remote.

## OAuth callback

`tf auth` listens on `127.0.0.1` for about five minutes, then stops. Set `OAUTH_BIND_HOST` to something else only when you must authorize from a different machine (for example a Tailscale address). The CLI prints a warning when the bind is not loopback. Register the exact `OAUTH_REDIRECT_URI` on the X app. State is checked; a mismatch aborts as a possible CSRF.

## One refresh token, one machine

X rotates the refresh token when it is used. Two hosts running `tf fetch` against the same `.tokens.json` will invalidate each other. Symptoms: 401s, then `tf auth` required. Keep a single scheduler.

## What is sent off the machine

The default build does not contact tweetfactory.sh. `TF_LICENSE_KEY` is not sent anywhere until a billing provider replaces `resolveProvider()` in `src/entitlements/index.ts`. That provider must not upload `tweets.db`, the persona, or OAuth tokens. See [the hardening plan](https://github.com/abhirupghosh/tweet-factory/blob/main/docs/BINARY_HARDENING.md). `tf login` and `tf sync` are a separate opt-in. Login does not upload the database. Other network calls happen only to services you configured:

| Call | When |
|---|---|
| X API | auth, fetch, enrich of X articles |
| Your LLM | `tf generate`, onboard generate. The default is the Claude Code CLI already logged in on the machine. |
| Tavily | `tf search`, `tf enrich`, `tf generate --timely`, `tf cron` |
| Notion | `tf notion`, cron sync |
| Slack | `tf notify`, `tf generate --post-to-slack`, cron’s pending ping |
| tweetfactory.sh | `tf login`, `tf sync push`, `pull`, `status`, `delete` |

Cloud sync encrypts tweet text, author descriptions, article extracts, Notion notes and page text, and persona and draft bodies before they are stored. The operator who holds `SYNC_ENCRYPTION_KEY` can decrypt them. Ids, usernames, metrics, tags, and filenames are stored in the clear so the account page can list files. Details: [Cloud sync](cloud-sync.md).

`tf analyze`, `tf flush`, and `tf refresh` do not call an LLM. `tf refresh` does call the X API. `tf update` downloads a public release binary and does not call the X API.

## Scraped text

Tweets, article extracts, Tavily results, and Notion pages are untrusted. `tf generate` wraps them in `<reference_data>` and strips a closing fence that appears inside that text. The Claude Code subprocess is started with `--tools ""`, `--disallowedTools "*,mcp__*"`, `--strict-mcp-config`, `--permission-mode dontAsk`, and `--max-turns 1`. `--allowedTools` only pre-approves tools, so an empty allow list is not the control. Direct API backends have no tools in this CLI either; they get a single completion.

## What this program will not do

It does not post, like, or bookmark on your behalf. The OAuth scopes are read plus `offline.access`. Publishing a draft is a separate action you take in the X client.

> **Verify.** `git status --ignored --short -- .env .tokens.json .cloud.json tweets.db` shows those paths ignored (once they exist). `stat -c '%a' .tokens.json` is `600` after a successful auth. After `tf login`, `stat -c '%a' .cloud.json` is `600`.

---

Source: https://docs.tweetfactory.sh/troubleshooting.md

# Troubleshooting

## 401 or “token expired”

The access token was refreshed and rejected, or the refresh token was rotated by another machine. Run `tf auth` once on the machine you want to keep, click Authorize, and stop the other host’s cron.

`No .tokens.json` means auth has not succeeded in this directory. Check `--dir` and the working directory.

## Callback problems

`Timed out waiting for authorization (5 min)` — the browser never hit the listener. Re-run `tf auth`. Confirm the X app callback is exactly `http://127.0.0.1:8675/callback` unless you overrode the port and redirect URI.

`State mismatch` — the callback was not for this attempt. Re-run auth; don’t reuse an old URL.

`Token exchange failed` — the client id, secret, or redirect URI doesn’t match the app. The redirect URI in the exchange is the one the CLI printed (`Redirect URI in use`).

Headless: `tf auth --no-browser`, open the URL elsewhere, and make sure that browser can reach the bind address.

## 403 on a source

The log says `SKIP LIKES` or similar. Bookmarks in particular require OAuth 2.0 user context and the `bookmark.read` scope. Re-check app permissions (Read) and re-run `tf auth` so the new scopes are granted.

## Rate limit

A 429 sleeps until `x-rate-limit-reset` plus two seconds, then retries that page. Let it sit.

## `TAVILY_API_KEY not set`

`tf search`, `tf enrich`, and `tf cron` need the key. `tf cron` fails at the enrich step even if fetch already succeeded. Use `tf refresh` when you only want a refresh. `--timely` on generate is best-effort: a missing key or a Tavily error is ignored and drafts still run.

## `claude` CLI not found

Install Claude Code and log in, or set `TF_LLM_PROVIDER` to `anthropic`, `openrouter`, or `openai` and the matching key. A provider set without its key throws `API key is not set`.

## Generate returned prose or invalid JSON

The model has to return a single JSON object matching the bundle. Zod throws otherwise. Re-run `tf generate`, or set `TF_LLM_MODEL` / `--model` to a model that follows the JSON instruction. `--json` shows the failure on stdout/stderr without the markdown file.

## Notion pages missing

The integration can only see pages you shared with it. `tf notion search` is the check. `sync` logs `unreachable` and skips a page that was unshared later.

## Slack did nothing

Unset `SLACK_WEBHOOK_URL` is a logged skip, not a crash. Cron only pings when the pending count is greater than 0. The first flush baselines to 0, so the first cron after a backfill often stays quiet. Fetch something new, run `tf flush`, then cron again.

## `tf onboard` won’t open

The TUI uses OpenTUI’s native addon. Build with `bun run build` on the same OS you run (the release workflow compiles per target for this reason). A dumb terminal or a missing addon fails at launch. `--selftest` is a one-frame smoke check in an environment where the renderer can start.

## Bun missing

`./setup_x.sh` installs it under `$HOME/.bun/bin`. Open a new shell or export that path. `deploy.sh` logs a warning and skips the rebuild if `bun` is absent.

## Wrong project directory

Commands read whichever root they discovered. If counts look empty, you are probably not in the checkout that holds `tweets.db`. Pass `--dir` or `cd` to the directory that contains `.env`.

## Persona still sounds generic

`persona/PERSONA.md` is missing, still the template (`@YOUR_HANDLE`), or very thin. `tf analyze` shows what the model can see from the database. Fill the voice rules and banned phrases, then generate again.

> **Verify.** After a fix, re-run the failing command once. `./setup_x.sh --check` should list the required OAuth keys as present and Bun as installed.

---

Source: https://docs.tweetfactory.sh/how-the-x-algorithm-works.md

# How the X (Twitter) algorithm works in 2026

**Last updated 2026-10-11.** This page reads the public For You pipeline. X is the product name. Search still calls the same system the Twitter algorithm. It is not a growth guide and not a measurement of anyone’s impressions.

It follows [`X_ALGORITHM_BOOST_PLAYBOOK.md`](https://github.com/abhirupghosh/tweet-factory/blob/main/X_ALGORITHM_BOOST_PLAYBOOK.md), 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, “Open-source X Recommendation Algorithm”). The production weight mirror in `home-mixer/params/param.rs` is stamped `last sync 2026-10-08T16:00:35Z`. The dated commit list is [X algorithm changes in 2026](x-algorithm-changes-2026.md). A file-by-file map of the GitHub repo is [Twitter algorithm on GitHub](twitter-algorithm-github.md).

Where a number appears below, it is a published default in that tree. Experiments can override defaults per viewer. `WeightPerturbationSigma` defaults to `0.0`.

## What a For You request does

`README.md` and `home-mixer/candidate_pipeline/phoenix_candidate_pipeline.rs` build a request in this order:

1. **Query hydration.** The viewer’s recent engagements (the model’s main input), follow list, blocks and mutes, muted keywords, posts already seen or served, and followed topics.
2. **Candidate sources, in parallel.** In-network: Thunder. Out-of-network: Phoenix retrieval, SimClusters, and a popular-posts list that has been on since the 2026-10-07 param sync. Tweet Mixer, the SID source, and the Phoenix MoE source exist and default off.
3. **Hydration.** Text, media, author, quote target, language, engagement counts, semantic id, and whether the author mutually follows the viewer.
4. **Pre-scoring filters.** Duplicates, age, the viewer’s own posts, out-of-network replies and reposts, muted keywords, blocks, posts already seen or served, and the other filters below.
5. **Scoring.** Phoenix predicts one value per action. A weighted sum turns those predictions into one number. When `vm-ranker` recomputes the sum, it applies author-diversity decay and an out-of-network factor. A cold-start lift can move a new post up.
6. **Selection.** `TopKScoreSelector` keeps the top 50 (`TOP_K_CANDIDATES_TO_SELECT` in `home-mixer/params/config.rs`). The served page is smaller (`RESULT_SIZE` 35, plus modules).
7. **DPP reorder.** `vm-ranker` runs a determinantal point process so neighboring posts are less similar (`vm-ranker/dpp.rs`). Defaults: enabled, theta `0.65`, pool rank `150`.
8. **Post-selection filters.** Visibility filtering, then conversation dedup.

Visibility (drop, notice, interstitial, or allow) is a separate service, `visibility-filtering/`. The ranker does not decide it.

## Where candidates come from

| Source | Default | What the code says |
|---|---|---|
| Thunder | on | Recent posts from accounts the viewer follows. Cap `ThunderMaxResults` 1200. Per author, the return caps in `thunder/config.rs` are 50 originals, 30 replies, and 100 videos. |
| Phoenix retrieval | on | Two-tower retrieval over engagement history. `PhoenixMaxResults` is 1000. The cold-start retrieval cap is 200. |
| SimClusters | on | Favorite-graph clusters (`LOG_FAV_BASED_TWEET`). The source keeps 800; the ANN query cap is 200. Candidate age cap is 48 hours. |
| Popular posts | on since 2026-10-07 | A shared list. Cap 500. The README describes the initial list as posts from the most-followed active accounts. |
| Tweet Mixer, SID, Phoenix MoE | off | Present in the tree, not on by default. |

The hard age cut for For You is `AgeFilter` at `MAX_POST_AGE` = 48 hours. A “Thunder keeps posts for two days” reading comes from a test constructor, not from that filter.

## Filters that run before a score exists

From the README’s filtering section and `home-mixer/filters/`:

- Older than 48 hours.
- Reposts and replies from accounts the viewer does not follow (`OONRetweetReplyFilter`). `EnablePhoenixOonReplies` defaults **false**.
- The viewer has blocked or muted the author.
- Already seen. A bloom filter plus an explicit seen-id set. Recycling the same post id does not get a second impression.
- The viewer’s muted keywords, including hashtag keywords.
- Subscriber-only posts the viewer cannot access.
- The viewer’s own posts (`SelfTweetFilter`).
- A protected author’s post, when the viewer does not follow them (`protected_author` in `visibility-filtering/rules/author_rules.rs`). Followers can still be shown it. A protected account gets no out-of-network For You distribution.

After selection, conversation dedup (`DedupConversationFilter`) keeps one post per conversation id. The highest score wins, whichever post that is. A reply can beat its own thread starter.

## How the number is computed

Phoenix emits a probability, or a continuous value such as dwell time, per head. `compute_weighted_score` in `xai-value-model/scoring.rs` is:

```
weighted = Σ (weight_i × prediction_i)
```

A weight multiplies **that viewer’s predicted probability** of the action (or a predicted duration). It does not multiply raw like or reply counts. The same comments say a report’s weight is large because a report is rare: the baseline probability of a report is more than 1000× lower than a like, so the coefficient has to be large for the prediction to move rank. “One report cancels N likes” is not a reading the code supports.

The published defaults, and the out-of-network and author-diversity multipliers, are on [the weights page](x-algorithm-engagement-weights.md).

`offset_score` then shifts a negative weighted sum so it stays sortable (`NEGATIVE_SCORES_OFFSET = 0.001`). With the published default `multiplier_pre_offset = false`, author diversity and the out-of-network factor multiply after that offset.

## What this tree does not contain

Trained Phoenix weights. The Grox classifier prompts (they are Jinja templates loaded by name, and the README says they are not in the repo). The numeric rule that turns `slop_score` or a safety label into a visibility decision. The experiment bucket a given viewer is actually in. A day-of-week posting constant.

The old quality gate is also gone. There is no `0.4` cutoff on the current Gemma screen. That screen parses an integer `slop_score` and stores it. No cutoff appears on that path.

Safety labels still exist. Grox PTOS categories in `grox/flows/ptos/state.py` are eleven: `HateOrAbuse`, `ViolentSpeech`, `ChildSafety`, `IllegalAndRegulatedBehaviors`, `Spam`, `SuicideOrSelfHarm`, `AdultContent`, `ViolentMedia`, `TerrorismOrViolentExtremism`, `CivicIntegrity`, `AgeGatingHarmfulText`. Spam subtypes include `SpamEngagementFarming`, `SpamEngagementTrading`, `SpamHashTagAbuse`, `SpamScamLinks`, `SpamBotProduced`, and `SpamPlatformManipulation`. The prompts that fire them are unpublished, so this page does not invent a threshold.

tweet-factory does not run this pipeline. [How drafts are scored](how-tweet-factory-scores-drafts.md) is a separate, local heuristic.

## Changelog

The pipeline above is commit `cb45b55`. Older snapshots of this same repository changed defaults without changing the request shape. The short list, with dates from the playbook and the repo README:

| Date | What changed in the published tree |
|---|---|
| 2026-07-24 | Mutual-follow reply boost settled at +15, after a test at +20 (`docs/BIDIRECTIONAL_BOOST_CHANGE.md`). |
| 2026-08-13 | README release: published weights, visibility filtering, and Phoenix training code. The demonstration model was replaced. |
| 2026-09-04 | `e4dcedd` dedupes in-network ids before a visibility-filtering lookup. |
| 2026-09-29 | README: Brazil 2026 election account list updated. The filter drops reported accounts unless the viewer follows them. |
| 2026-10-06 | `e62790c` moves the vm-ranker cluster default from `Experiment6` to `Experiment1`. |
| 2026-10-07 | `78460ca` sets `PostUnexploredWeight` from 0.02 to 0.015 and turns the popular-posts source on. |
| 2026-10-08 | `35650fb` adds favorite-count hydration on the Phoenix index. Video carousel params ship default off. Param mirror stamp `2026-10-08T16:00:35Z`. |
| 2026-10-09 | `cb45b55` changes ranker attention and sequence packing inside `phoenix/xrex/`. The param file bump is the sync timestamp. |

The full notes are on [X algorithm changes in 2026](x-algorithm-changes-2026.md). A browser draft scorer, separate from this ranker, is [tweetfactory.sh/score](https://tweetfactory.sh/score/).

## Related

- [Engagement weights](x-algorithm-engagement-weights.md)
- [Myths: links, hashtags, bookmarks, Premium](x-algorithm-myths.md)
- [Why replies stay in network](why-replies-stay-in-network.md)
- [X algorithm changes in 2026](x-algorithm-changes-2026.md)

## FAQ

### How does the Twitter algorithm work in 2026?

Same pipeline as the X algorithm. At commit cb45b55 the For You request hydrates the viewer, pulls in-network posts from Thunder and out-of-network posts from Phoenix retrieval, SimClusters, and a popular-posts list, drops posts that fail age, social, seen, and reply filters, scores the rest as a weighted sum of predicted actions, keeps the top 50, reorders for diversity, then applies visibility filtering and conversation dedup.

### How does the X algorithm work?

The open-source For You path, at commit cb45b55, hydrates the viewer, pulls candidates from Thunder (in network) and from Phoenix retrieval, SimClusters, and a popular-posts list (out of network), drops posts that fail age, social, seen, and reply filters, scores the rest as a weighted sum of predicted actions, keeps the top 50, reorders for diversity, then applies visibility filtering and conversation dedup.

### Is the X algorithm open source explained by one file of weights?

The weight defaults are published in `home-mixer/params/param.rs` and duplicated, with one difference, in `vm-ranker/params.rs`. The ranker is the whole pipeline above. Trained model weights and the Grox prompts are not in the repo. A default of 0 means that head is off in the mirrored primary config, not that the head does not exist.

### Does the X algorithm rank by raw like counts?

No. `home-mixer/params/param.rs`, `xai-value-model/scoring.rs`, and the README’s 2026-08-14 note say a weight multiplies a predicted probability or a predicted duration. `favorite`’s published coefficient is 0.5. Copy-link share is 20.0, reply is 5.0, and quote is 5.0. Those are coefficients on probabilities, not “one reply equals ten likes.”

---

Source: https://docs.tweetfactory.sh/x-algorithm-changes-2026.md

# X (Twitter) algorithm changes in 2026

**Last updated 2026-10-11.** This is a changelog of the public tree [`xai-org/x-algorithm`](https://github.com/xai-org/x-algorithm), gathered in [`X_ALGORITHM_BOOST_PLAYBOOK.md`](https://github.com/abhirupghosh/tweet-factory/blob/main/X_ALGORITHM_BOOST_PLAYBOOK.md) and the repo README. Search phrases like “X algorithm news” and “Twitter algorithm updates 2026” land here. Commit subjects in this list are “Open-source X Recommendation Algorithm” unless the README gives a different label. The repo does not attach these diffs to a personal announcement, so this page does not invent one.

The pipeline those commits sit on is [How the X (Twitter) algorithm works](how-the-x-algorithm-works.md).

## 2026-10-09 — `cb45b55`

Ranker attention and sequence packing inside `phoenix/xrex/`. The param file is touched to bump the sync timestamp. This is the commit the rest of these docs quote. Weight values in `home-mixer/params/param.rs` are the 2026-10-08 mirror (`last sync 2026-10-08T16:00:35Z`).

## 2026-10-08 — `35650fb`

Video carousel parameters, default off. A video aspect-ratio hydrator. Favorite-count hydration on the Phoenix retrieval index (`phoenix-rankall/src/hydrate/fav_counts.rs`), so popularity can enter what is indexed, separate from the ranking sum.

## 2026-10-07 — `78460ca`

`PostUnexploredWeight` moves from 0.02 to 0.015. `EnablePopularPostsSource` moves from false to true. The popular-posts source cap in the playbook is `PopularPostsMaxResults` 500. The README describes that list as starting from the most-followed active accounts.

## 2026-10-06 — `e62790c`

The vm-ranker cluster default moves from `Experiment6` to `Experiment1`. The playbook does not describe what traffic each experiment name serves. A default change is not a measurement of whose feed flipped.

## 2026-09-29 — Brazil election list

The README says the account list behind `Brazil2026ElectionFilter` was updated on this date. The filter removes posts from accounts reported to Brazil’s electoral court unless the viewer follows them (`home-mixer/filters/brazil_2026_election_filter.rs`). That is a candidate filter, not a weight.

## 2026-09-04 — `e4dcedd`

A community change that dedupes in-network ids before a visibility-filtering lookup. Visibility itself stays a separate service. See [Shadowban on X](shadowban-on-x.md).

## 2026-08-13 — README release

The README’s August 13, 2026 section is the large public cutover:

- Key configuration parameters, including the weights that blend predicted actions.
- Code for systems that can filter a post out of For You.
- Phoenix demonstration model replaced by training code and synthetic data, so a proof-of-concept training run is possible.
- `visibility-filtering/` decides show, drop, or interstitial.
- Label-producing systems named in that section include botmaker, scarecrow, agatha, bdsm, `user-cred-v2/`, media models, and enforcement.
- SimClusters ships as an out-of-network source beside Thunder and Phoenix retrieval.

The old demo weights (favorite 1.0, reply 0.5) lived in `phoenix/run_pipeline.py`, which is not in the tree after this release.

## 2026-07-24 — mutual reply boost

`docs/BIDIRECTIONAL_BOOST_CHANGE.md` in the x-algorithm repo records the reply boost on an original from a mutual follow: tested at +20, settled at +15 on 2026-07-24. The published reply weight is then 5, or 20 on that original. A reply you send does not receive the +15.

## What did not change

Still absent after these commits: a day-of-week posting constant, a coded percentage penalty for a link in the post (`open_link` remains +0.2), a bookmark head, a Premium term in the weighted sum, and a numeric cutoff on `slop_score`. The Grox prompts are still not in the repo. Experiments can still override a default per viewer. `WeightPerturbationSigma` defaults to 0.0.

## Related

- [How the X (Twitter) algorithm works](how-the-x-algorithm-works.md)
- [Twitter algorithm on GitHub](twitter-algorithm-github.md)
- [Myths: links, hashtags, bookmarks, Premium](x-algorithm-myths.md)

## FAQ

### What changed in the X algorithm in 2026?

In the public repository: the August 13 release published weights and visibility filtering and replaced the demo Phoenix model; the mutual reply boost settled at +15 on July 24; popular posts turned on and `post_unexplored` became 0.015 on October 7; favorite counts were added to Phoenix index hydration on October 8. Details and commit ids are the sections above.

### Where is the Twitter algorithm news for 2026?

This page is that list, limited to commits and README notes. It does not reprint social-post commentary. If a claim is not tied to a path in `xai-org/x-algorithm`, it is not on this page.

### Did a 2026 update punish links or hashtags?

Not in these commits. `open_link` is +0.2. There is no hashtag counter in the ranking sum. `SpamHashTagAbuse` and `SpamScamLinks` are classifier labels whose prompts are unpublished. See [the myths page](x-algorithm-myths.md).

---

Source: https://docs.tweetfactory.sh/x-algorithm-engagement-weights.md

# How to grow on X, from the published engagement weights

“How to grow on X” is answerable from this tree only as a list of heads with large published coefficients. These are default weights, not a ranking of what gets the most reach, and not a promise of impressions. Each one multiplies a predicted probability, or a predicted duration, for a specific viewer. The table is from [`X_ALGORITHM_BOOST_PLAYBOOK.md`](https://github.com/abhirupghosh/tweet-factory/blob/main/X_ALGORITHM_BOOST_PLAYBOOK.md), copied from `home-mixer/params/param.rs` in [`xai-org/x-algorithm`](https://github.com/xai-org/x-algorithm) at commit [`cb45b55`](https://github.com/xai-org/x-algorithm/commit/cb45b55). The file’s sync stamp is `2026-10-08T16:00:35Z`.

The writing consequences the playbook draws from the same table: an original to mutual followers (reply weight 20, and no 0.75 reply discount), a line worth copying (weight 20), quoting (5), or sending in a DM (5), a reason to follow (4), and one post per conversation because dedup and author diversity (second post ×0.625) both shrink a burst. A like is 0.5. None of those ratios is “one reply equals N likes.” A single draft can be scored in the browser at [tweetfactory.sh/score](https://tweetfactory.sh/score/); that page is a heuristic, and this table is the ranker.

Home-mixer asks `vm-ranker` to recompute the sum (`compute_value_model: true`). The same literals live in `vm-ranker/params.rs`, except `PostUnexploredWeight`, which is `0.015` in home-mixer and `0.02` in vm-ranker. When vm-ranker’s feature-switch config resolves, that copy produces the served score. If vm-ranker has no ranking config, or the RPC fails, home-mixer serves its in-process sum instead, and that path turns author diversity and the in-network reply/repost discount off.

## Published default weights

| Head | Default | Kind |
|---|---:|---|
| `share_via_copy_link` | 20.0 | probability |
| `reply` | 5.0 | probability. **+15.0** on an original post from a mutual follow |
| `share_via_dm` | 5.0 | probability |
| `quote` | 5.0 | probability |
| `follow_author` | 4.0 | probability |
| `share` | 2.0 | probability |
| `retweet` | 1.0 | probability |
| `favorite` | 0.5 | probability |
| `click` | 0.3 | probability |
| `open_link` | 0.2 | probability |
| `video_open` | 0.07 | probability |
| `photo_expand` | 0.05 | probability |
| `dwell` | 0.05 | probability. The bidirectional dwell boost shipped at 0.0 |
| `quoted_click` | 0.05 | probability |
| `post_unexplored` | 0.015 | probability. In-network only, unless `PostUnexploredIncludeOutOfNetwork` (default false) |
| `click_dwell_time` | 0.4 | continuous, predicted seconds-class value |
| `dwell_time` | 0.004 | continuous |
| `profile_click` | 0.0 | off |
| `vqv` | 0.0 | off. Also gated: video longer than 10 seconds and a viewer with fewer than 10,000 followers |
| `quoted_vqv` | 0.0 | off |
| `video_continuation` | 0.0 | off |
| `user_video_continuation` | 0.0 | off |
| `profile_visit_secs` | 0.0 | off |
| `not_interested` | −47.52 | probability |
| `block_author` | −31.2 | probability |
| `mute_author` | −58.8 | probability |
| `report` | −234.0 | probability |
| `not_dwelled` | −0.02 | probability |

There is no bookmark head in `xai-value-model/phoenix_scores.rs`.

`favorite` at 0.5 is a real but small term. The older “likes are the primary sort key” line came from a demo file, `phoenix/run_pipeline.py`, that is not in this tree. The August 13, 2026 release replaced that demonstration model with training code and these published weights.

## After the sum

**Author diversity** (`diversity_multiplier` in `xai-value-model/scoring.rs`). Posts from one author are ordered by score. The k-th extra post is multiplied by `(1 − floor) × decay^k + floor`. `vm-ranker/params.rs` defaults: enabled, `decay = 0.5`, `floor = 0.25`.

| Extra posts already ahead (k) | Multiplier |
|---:|---:|
| 0 (first) | 1.00 |
| 1 | 0.625 |
| 2 | 0.4375 |
| 3 | 0.34375 |
| large k | approaches 0.25 |

This is one viewer’s candidate pool for one request. It is not a daily posting cap.

**Out-of-network factor** (`oon_applies`):

- An account the viewer does not follow: × `OonWeightFactor` **0.75**.
- An account the viewer follows, when the post is a reply or a repost: also × 0.75, because `EnableOonRescoreForInNetworkRepliesRetweets` defaults true.
- An original post from an account the viewer follows: × 1.
- Topic-page requests use `TopicOonWeightFactor` **0.5**.
- `NewUserOonWeightFactor` **0.00001** applies only when account age is under `NewUserAgeThresholdSecs`. That threshold’s default is **0**, so the path does not fire on the published default.

**Mutual-follow reply boost.** An original post (not a reply, not a repost) whose author the viewer mutually follows uses reply weight `5.0 + 15.0 = 20.0` (`ValueModelWeights::reply_weight_for`). The dwell boost parameter exists and defaults to 0. The history of that July 2026 rollout is `docs/BIDIRECTIONAL_BOOST_CHANGE.md` in the x-algorithm repo.

**Cold start** can lift a post toward slots 15–16 when it has under 200 impressions, is younger than two hours (`ColdStartMaxPostAgeSecs` 7200), and the author has under 50,000 followers. Thompson sampling is on. The playbook’s reading: this is a position lift for unscored inventory, not a velocity multiplier on likes.

**DPP** then reorders the top of the pool so near-paraphrases sit further apart, even when each post scores well alone.

Video and profile terms that are products rather than raw heads (`video_continuation`, `user_video_continuation`, `profile_visit`) ship at weight 0 in the vm-ranker params and in home-mixer’s in-process scorer.

## What the coefficients suggest, and what they do not

The playbook’s “worth writing toward” list follows from these coefficients. It is still a prediction about a specific viewer. None of it is a guaranteed multiplier on impression count.

- An original post to people who follow you back skips the 0.75 reply/repost discount, and the reply head they are scored with is 20 instead of 5. A reply you send does not receive that boost.
- Quote, copy-link, and DM-share are the large positive probability heads (5, 20, and 5).
- `follow_author` at 4.0 is eight times `favorite`.
- A reply is aimed at people who already follow you. Out-of-network replies are filtered before scoring. See [why replies stay in network](why-replies-stay-in-network.md).
- One strong post per conversation survives dedup.
- A second post from you already in that viewer’s pool is ×0.625.

There is no Tuesday-morning constant in the repo.

## Related

- [How the pipeline is built](how-the-x-algorithm-works.md)
- [Myths about links, hashtags, bookmarks, and Premium](x-algorithm-myths.md)
- [How tweet-factory scores a draft](how-tweet-factory-scores-drafts.md)

## FAQ

### How do you grow on X according to the open-source weights?

Write originals that a mutual follower can reply to, quote, copy as a link, or follow you for. Those heads are 20 (reply, on a mutual’s original), 20 (copy-link), 5 (quote), 5 (DM share), and 4 (follow). Keep one strong post per conversation. Stay inside the 48-hour age filter. The code does not publish an impression multiplier for doing any of that.

### What does the X algorithm reward?

On the published defaults, the largest positive probability weights are copy-link share (20), reply (5, or 20 on an original from a mutual), DM share (5), quote (5), and follow (4). A like is 0.5. Binary dwell is 0.05. Click-dwell’s continuous weight is 0.4. Report, mute, block, and not-interested are large negative coefficients because those events are rare.

### Are likes the main For You signal in the 2026 open-source code?

Not in this tree. `favorite` is 0.5. The “likes are the primary sort key” sentence belonged to a demo script that is no longer in the repo. Reply’s coefficient is 10× favorite’s, and 40× on a mutual’s original (20 / 0.5). That ratio is not “one reply equals ten likes,” because both numbers scale probabilities.

### Do negative actions wipe out a post?

`not_interested` is −47.52, `mute_author` is −58.8, `block_author` is −31.2, and `report` is −234. The code’s own comment is that those coefficients are large because the baseline probabilities are tiny. Coordinated reports from people who are not served the post in Home do not enter this prediction. The playbook does not support a fixed “one report cancels N likes” rule.

---

Source: https://docs.tweetfactory.sh/best-time-to-post-on-x.md

# Best time to post on X

**Last updated 2026-10-11.** “Best time to post on X,” and the older “best time to post on Twitter,” are usually answered with a clock. Commit [`cb45b55`](https://github.com/xai-org/x-algorithm/commit/cb45b55) does not contain that clock. The ranker has recency. It does not have a time-of-day weight.

## What is actually in the code

`AgeFilter` drops a post older than `MAX_POST_AGE` = 48 hours (`home-mixer/params/config.rs`, wired in `phoenix_candidate_pipeline.rs`). SimClusters uses the same horizon: `SimclustersMaxCandidateAgeHours` is 48. After 48 hours a post is not a For You candidate through these sources, whatever hour it was published.

Cold start can lift a post toward slots 15–16 when three conditions hold (`home-mixer/scorers/author_cold_start.rs`): under 200 impressions, younger than `ColdStartMaxPostAgeSecs` (7200, two hours), and the author has under 50,000 followers. Thompson sampling is on. The playbook’s reading is a position lift for unscored inventory, not a velocity multiplier on likes, and not “the first 30 minutes compound into out-of-network.”

Out-of-network retrieval is embedding similarity, plus favorite counts on the Phoenix index as of the 2026-10-08 commit `35650fb` (`phoenix-rankall/src/hydrate/fav_counts.rs`). That hydration is about what gets indexed. It is not an hour-of-day feature.

Thunder’s `post_retention_seconds` is a process argument (`thunder/args.rs`). The figure `2 * 24 * 60 * 60` appears in `PostStore` tests, not as the production For You cut. The cut that is a constant is the 48-hour `AgeFilter`.

## What is not in the code

The playbook’s correction table is explicit: there is no Tuesday-to-Thursday constant, and no 9–10am constant. “When your followers are awake is a property of your account, not of this code.” This page repeats that sentence because it is the evidence-based guidance the repository supports. It does not add a recommended hour, a timezone table, or a claim that posting at a popular time multiplies impressions. Those numbers are not in `param.rs`.

Author diversity is also not a clock. The second post from you already in one viewer’s candidate pool is ×0.625 (`decay` 0.5, `floor` 0.25 in `vm-ranker/params.rs`). That is per request, not “four posts a day is banned.” Spacing posts matters inside one viewer’s pool. It does not name a best hour.

## A practical reading that stays inside the file

Post something that can still be a candidate: younger than 48 hours, and, if you are under the follower cap and still under 200 impressions, still inside the two-hour cold-start window if you care about that position lift. Do not treat a blog’s “best time” grid as a ranker coefficient. If you want a draft scored against the published weights rather than against a clock, paste it at [tweetfactory.sh/score](https://tweetfactory.sh/score/). The weights themselves are on [How to grow on X](x-algorithm-engagement-weights.md).

## Related

- [How the X (Twitter) algorithm works](how-the-x-algorithm-works.md)
- [How to grow on X](x-algorithm-engagement-weights.md)
- [X algorithm changes in 2026](x-algorithm-changes-2026.md)

## FAQ

### What is the best time to post on X?

The open-source ranker does not say. It has no day-of-week term and no hour-of-day term. It does drop posts older than 48 hours, and it can lift a post in its first two hours when impressions are under 200 and the author has under 50,000 followers.

### Does the Twitter algorithm reward posting in the morning?

Not with a published coefficient. The old “Tuesday to Thursday, 9–10am” line is in the playbook’s correction table as something this tree does not contain.

### Does posting more often beat the clock?

Author diversity discounts later posts from you inside one viewer’s pool (second post ×0.625). That is a same-request penalty, not a daily cap, and not a substitute for a best-hour chart.

---

Source: https://docs.tweetfactory.sh/x-algorithm-myths.md

# Myths: links, hashtags, bookmarks, Premium

People repeat fixed penalties for links, hashtags, bookmarks, and Premium. The open-source For You tree at [`cb45b55`](https://github.com/xai-org/x-algorithm/commit/cb45b55) does not contain those penalties. Citations below are the ones gathered in [`X_ALGORITHM_BOOST_PLAYBOOK.md`](https://github.com/abhirupghosh/tweet-factory/blob/main/X_ALGORITHM_BOOST_PLAYBOOK.md). This page does not add a percentage the repo does not publish.

tweet-factory’s draft score is a separate local heuristic. It uses these published weights and does not reintroduce the retired penalties below. [How drafts are scored](how-tweet-factory-scores-drafts.md) is that heuristic. This page is the ranker.

## Do links hurt reach on X?

`open_link` is a positive head with published weight **+0.2**. There is no median-engagement constant, and no “link in the body means near-zero reach” constant, in the repo.

Leaving the app can still change other predictions. `dwell` (binary weight 0.05) and `click_dwell_time` (continuous weight 0.4) are separate heads. A scorer that predicts less dwell after an off-site click is scoring those heads, not applying a secret link penalty.

`SpamScamLinks` is a Grox spam subtype. It is a safety label, not a dwell rule. The prompt that fires it is not in the repo, so there is no published numeric cutoff.

The prompt `tf generate` sends says open-link is a small positive and that a URL does not zero the post. `scoreDraft` has no open-link row. A URL only withholds a 0.1 copy-link strength bonus. `roast()` calls that same function, without account calibration. The formula is on [how drafts are scored](how-tweet-factory-scores-drafts.md).

## Do hashtags cut reach by a fixed percent?

There is no hashtag counter in the ranking sum. The myth that “3+ hashtags cut reach 40%” is unsupported as a fixed penalty. No 40% figure appears in the playbook’s reading of this tree.

`SpamHashTagAbuse` is a classifier label. Its prompt is unpublished. `MutedKeywordFilter` can drop a post when the **viewer** has muted that keyword, including a hashtag keyword. That is the viewer’s mute list, not a global hashtag tax.

`scoreDraft` treats three or more `#` characters as stuffing: it raises report, mute, and not-interested strength, and adds more report strength at six or more. That is an editorial risk on the negative heads. It is not a percentage cut, and it is not a counter in the ranking sum. The old quality-classifier file (`grox/classifiers/content/banger_initial_screen.py`) is not in the current tree.

## Do bookmarks raise the author’s score?

There is no bookmark head in `xai-value-model/phoenix_scores.rs`.

Bookmarks are a viewer-history feature: `EngagementSignalType::Bookmark` in `home-mixer/models/engagement_signals.rs`, capped at 15 per type by `EngagementSignalsMaxPerType`. They steer what **that viewer** is retrieved next. They are not a term in the author’s score.

SimClusters candidate embeddings are favorite-based (`LOG_FAV_BASED_TWEET`), not bookmark-based.

Saving a post can still matter to the person who saved it. It does not show up as a coefficient next to reply or copy-link.

## Does Premium change the organic score?

The playbook’s check: there is no Premium term, and no sentiment term, in the weighted sum. Subscription state gates subscriber-only posts (`IneligibleSubscriptionFilter`) and ad spacing. It does not add an organic-score bonus in this tree.

“RealGraph” does not appear in the repo. Advice that says “reply to bigger accounts so RealGraph compounds” is not grounded in this code. Out-of-network replies are dropped before scoring. See [why replies stay in network](why-replies-stay-in-network.md).

## Other retired lines

| Claim that used to circulate | In commit cb45b55 |
|---|---|
| A VLM quality score under 0.4 drops the post | That file is gone. The current screen emits `slop_score` with no published cutoff. |
| Images are worth about 2.5× engagement | No such coefficient. `photo_expand` is 0.05 and `video_open` is 0.07. `vqv` is 0. |
| Phoenix out-of-network retrieval returns only the top 200 | `PhoenixMaxResults` is 1000. 200 is the cold-start retrieval cap and the SimClusters ANN cap. |
| Posting four times a day is a hard penalty | Author decay is per request pool (second post ×0.625). DPP can separate near-duplicates in one slate. Neither is a daily cap. |
| Tuesday to Thursday, 9–10am, is a ranker constant | No day-of-week constant. Cold start is two hours and 200 impressions, for authors under 50,000 followers. |

## Related

- [The weight table](x-algorithm-engagement-weights.md)
- [How a For You request is built](how-the-x-algorithm-works.md)
- [How tweet-factory scores drafts](how-tweet-factory-scores-drafts.md)

## FAQ

### Do links hurt reach on X?

The published ranker has `open_link` at +0.2. It does not contain a percentage penalty or a “near-zero median engagement” constant for a link in the post. Dwell and click-dwell are separate predictions, and `SpamScamLinks` is an unpublished safety classifier, not a dwell rule.

### Does the X algorithm punish hashtags?

Not with a counter in the score. Three or more hashtags are not a coded demotion in this tree. `SpamHashTagAbuse` is a safety label whose prompt is not published, and a viewer can mute a hashtag keyword on their own account.

### Do bookmarks or Premium boost a post’s For You score?

Bookmarks are not a scoring head. They are capped viewer-history features. Premium is not a term in the sum. Subscription state decides who can see a subscriber-only post, and it affects ad spacing. It is not an organic ranking bonus in the published defaults.

### Why does “twitter algorithm reddit” disagree with this page?

Search for that phrase is people comparing anecdotes. This page does not summarize a forum. It answers from commit cb45b55: there is no coded “links cut reach” percentage, no hashtag counter in the sum, no bookmark head, and no Premium term in the organic score. A thread can still be describing dwell after a click, a viewer’s muted keyword, or a visibility label whose prompt is not in the repo. Those are different mechanisms, listed above. The dated code changes are on [X algorithm changes in 2026](x-algorithm-changes-2026.md).

### Is the Twitter algorithm messed up?

The repository does not contain a broken-flag or a status field by that name. What it does contain, as of 2026-10-09, is a weighted sum of predicted actions, a 48-hour age filter, out-of-network reply filtering, and a separate visibility service. Several 2026 commits changed defaults (popular posts turned on, `post_unexplored` moved from 0.02 to 0.015, the mutual reply boost settled at +15). A feed that feels different can be one of those defaults, or an experiment bucket the public tree does not name for a given viewer. The commit list is [the 2026 changelog](x-algorithm-changes-2026.md).

---

Source: https://docs.tweetfactory.sh/shadowban-on-x.md

# Shadowban on X: what the code actually filters

**Last updated 2026-10-11.** Commit [`cb45b55`](https://github.com/xai-org/x-algorithm/commit/cb45b55) does not use the word shadowban. People use it for “my post is not showing.” The repository splits that outcome into two mechanisms, and it does not tell you which one applied to a given account.

## Ranking is not visibility

The README states the split. Ranking sets order. Whether a post can be shown at all is [`visibility-filtering/`](https://github.com/xai-org/x-algorithm/tree/cb45b55/visibility-filtering), from the viewer’s own blocks and mutes and from labels other systems attach. `VFFilter` and `AncillaryVFFilter` drop a candidate when visibility-filtering answered drop, including when a parent, quote, or repost target was dropped.

`visibility-filtering/rules/registry.rs` evaluates rules into verdicts. The actions in that file include:

- `ActionSpec::Drop` — withheld as a drop.
- `ActionSpec::Tombstone` — withheld as a tombstone.
- `ActionSpec::Appealable` — the post can still be shown with a notice.
- `ActionSpec::LimitedEngagement` — engagement on the post is limited.
- `ActionSpec::MediaRestriction` — media is restricted while the post can remain.

The README’s short version of the same service is: show a post, drop it, or show it behind an interstitial. A further set of rules applies only when the post is a recommendation from an account the viewer does not follow, and those rules can only drop. The same post can be allowed to a follower. Both sets are listed in `registry.rs`.

`protected_author` in `visibility-filtering/rules/author_rules.rs` drops the post when the author is protected and the viewer does not follow them.

Labels come from Grox, media models, Agatha, BDSM, Scarecrow, and botmaker. Grox PTOS categories in `grox/flows/ptos/state.py` include spam, with subtypes such as `SpamEngagementFarming`, `SpamHashTagAbuse`, `SpamScamLinks`, and `SpamPlatformManipulation`. The classifier prompts are not in the repo. The playbook is explicit that the numeric rule turning `slop_score` or a safety label into a visibility decision is not published. This page cannot say “score above N means you are filtered.”

The README describes an “Under the Hood” view that reports aggregate label statistics on an account and its posts, including legal withholding by country. That tool is not this website. Matching a label you can see there to `registry.rs` is the path the README suggests. This page does not have your labels.

## Filters that remove a post before a score exists

These are not visibility-filtering. They run in `home-mixer/filters/` and never produce a rank:

| Filter | What it drops |
|---|---|
| `AgeFilter` | Older than 48 hours |
| `OONRetweetReplyFilter` | Replies and reposts from accounts the viewer does not follow (`EnablePhoenixOonReplies` defaults false) |
| `AuthorSocialgraphFilter` | Author the viewer blocked or muted |
| `PreviouslySeenPostsFilter` | Already impressed or served |
| `MutedKeywordFilter` | The viewer’s muted keywords, including hashtags |
| `IneligibleSubscriptionFilter` | Subscriber-only posts the viewer cannot access |
| `Brazil2026ElectionFilter` | Accounts reported to Brazil’s electoral court, unless the viewer follows them |
| `SelfTweetFilter` | Your own posts, in your own For You |

A post that loses here is absent from that viewer’s For You. Followers can still be eligible when the rule is the out-of-network reply filter or the protected-author rule. That is a narrower outcome than “nobody can see it,” and the code does not collapse those cases into one word.

## What a missing post is not

It is not, by itself, evidence of a reputation multiplier. `UserCredV2` is not read by `home-mixer` or by `visibility-filtering` in this commit. See [What is TweepCred](what-is-tweepcred.md). It is also not the 0.75 out-of-network factor. That factor discounts a score. It does not drop the post. The drop list is the table above plus visibility-filtering.

tweet-factory does not query visibility for your account. The draft scorer at [tweetfactory.sh/score](https://tweetfactory.sh/score/) scores wording against published weights. It does not tell you whether a label withheld a post.

## Related

- [How the X (Twitter) algorithm works](how-the-x-algorithm-works.md)
- [X algorithm changes in 2026](x-algorithm-changes-2026.md)
- [Myths: links, hashtags, bookmarks, Premium](x-algorithm-myths.md)

## FAQ

### Am I shadowbanned on X?

This repository cannot say. It does not define shadowban. It can drop a post in visibility-filtering, tombstone it, limit engagement, or remove it before scoring for age, blocks, mutes, seen-state, keywords, subscription, or the Brazil election list. Which rule fired is not in the public request logs this site can see.

### Is a shadowban the same as a low For You score?

No. A low score is still a ranked candidate. A drop in `VFFilter` or in `AgeFilter` never receives that score for that viewer. Out-of-network posts that remain are multiplied by 0.75. That is a discount, not a ban.

### Do links or hashtags trigger a shadowban in this code?

There is no such rule in the ranking sum. `open_link` is +0.2. Hashtags are not a counter. `SpamScamLinks` and `SpamHashTagAbuse` are safety labels whose prompts and thresholds are unpublished, so a spam label can still affect visibility without a percentage published here. See [the myths page](x-algorithm-myths.md).

---

Source: https://docs.tweetfactory.sh/why-replies-stay-in-network.md

# Tweet reply generator, and why replies stay in network

A tweet reply generator can write the text. It cannot put that reply on the For You page of people who do not follow you. A reply under someone else’s post does not enter that person’s followers’ For You through the open-source pipeline. The filter is explicit. The same tree also discounts replies that do stay in network. Both facts are in [`X_ALGORITHM_BOOST_PLAYBOOK.md`](https://github.com/abhirupghosh/tweet-factory/blob/main/X_ALGORITHM_BOOST_PLAYBOOK.md), from [`xai-org/x-algorithm`](https://github.com/xai-org/x-algorithm) commit [`cb45b55`](https://github.com/xai-org/x-algorithm/commit/cb45b55).

tweet-factory will draft reply-shaped variants. `tf generate` asks for ideas aimed at copy-link, reply, quote, or follow. Text that starts with `@` is scored as a reply: reply weight 5, not the mutual-original 20 (`src/rank/score.ts`). You still publish it yourself. The [tweet generator](ai-tweet-writer-your-voice.md) page is the drafting tool. This page is the distribution limit.

## Out of network, the reply is dropped

`OONRetweetReplyFilter` removes reposts and replies from accounts the viewer does **not** follow. `EnablePhoenixOonReplies` defaults **false**, so a reply to someone who does not follow you is not an out-of-network For You candidate.

Replies whose parent failed to hydrate are dropped for everyone, followers included.

A protected author is a separate rule: `protected_author` drops the post when the viewer does not follow them. A protected account gets no out-of-network For You distribution. Followers can still be shown the post.

Thunder, the in-network source, does keep a replies deque. Return cap in `thunder/config.rs`: 30 replies per author, beside 50 originals and 100 videos. That is “posts from accounts this viewer follows,” not “replies this author left on a stranger’s post, shown to the stranger’s audience.”

## In network, a reply is scored lower than an original

When the viewer does follow the author, a reply or a repost is still multiplied by `OonWeightFactor` **0.75**. `EnableOonRescoreForInNetworkRepliesRetweets` defaults true. An original post from a followed account is ×1.

The mutual-follow reply boost does not apply to a reply you send. `CandidateScoringInputs::bidirectional_boost_eligible` requires `!is_reply && !is_retweet`. The +15 on the reply head (5.0 + 15.0 = 20.0) is for an **original** post whose author the viewer mutually follows.

So the large “reply” coefficient is mostly “will this viewer reply to this original,” not “this reply should travel.”

## One post per conversation

`DedupConversationFilter` keeps a single post per conversation id. The highest score wins. A reply can beat its own thread starter, and then the starter is the one that drops. Later posts in a thread compete with the first post and with each other.

That is why the playbook says the first post has to stand alone. It is a dedup rule, not a claim about thread length and virality.

## What the code does not say

It does not say replies are worthless inside the group that already follows you. Reply’s coefficient on an in-network original is still 5.0, or 20.0 when the follow is mutual. It does not say a reply is invisible to the person you replied to, or to your followers via Thunder. It does not name RealGraph. That string is not in the repo.

`src/tui/persona.ts` writes `algorithmPriorsBlurb()` from `src/rank/weights.ts` into `persona/PERSONA.md`. That blurb says out-of-network replies are filtered, and that the reply weight is 20 on an original a mutual follow sees. It does not name RealGraph. The ranker facts on this page are the source of that blurb.

## Related

- [How the X algorithm works](how-the-x-algorithm-works.md)
- [Engagement weights](x-algorithm-engagement-weights.md)
- [Myths: links, hashtags, bookmarks, Premium](x-algorithm-myths.md)

## FAQ

### Can a tweet reply generator get replies onto non-followers’ feeds?

No path in this pipeline does that. `OONRetweetReplyFilter` drops replies and reposts from accounts the viewer does not follow, and `EnablePhoenixOonReplies` defaults false. A generated reply has the same filter as a reply you typed. The generator changes the wording. It does not change the filter.

### Why don't replies reach non-followers?

`OONRetweetReplyFilter` drops replies and reposts from accounts the viewer does not follow, and `EnablePhoenixOonReplies` defaults false. A reply on a stranger’s post is not an out-of-network For You candidate in this pipeline. If the parent tweet fails to hydrate, the reply is dropped for followers too.

### Does the out-of-network discount also hit replies to your own followers?

Yes. A reply or repost from an account the viewer follows is multiplied by 0.75, because `EnableOonRescoreForInNetworkRepliesRetweets` defaults true. An original from a followed account is not discounted. The +15 mutual reply boost applies to that original, not to a reply.

### Can a reply outrank the start of a thread?

Yes. Conversation dedup keeps the highest-scoring post in the conversation. A reply can be the one that remains, and the thread starter is then ineligible for that request.

---

Source: https://docs.tweetfactory.sh/how-to-reset-your-x-algorithm.md

# How to reset your X (Twitter) algorithm

**Last updated 2026-10-11.** People search “how to reset the X algorithm” and “how to reset the Twitter algorithm” for a switch that clears For You. Commit [`cb45b55`](https://github.com/xai-org/x-algorithm/commit/cb45b55) of [`xai-org/x-algorithm`](https://github.com/xai-org/x-algorithm) does not contain that switch. There is no reset endpoint, no “clear my algorithm” parameter, and no published timer that says old likes fall out of the model after N days.

What the code does publish is the input list for the next request. That list is the only honest answer.

## What the next For You request actually reads

`README.md` and the playbook’s reading of `home-mixer/candidate_pipeline/phoenix_candidate_pipeline.rs` hydrate a request from:

1. The viewer’s recent engagements. The README calls this the model’s main input.
2. The follow list.
3. Blocks and mutes.
4. Muted keywords.
5. Posts already seen and already served.
6. Followed topics.

Phoenix retrieval is a user tower over that engagement history. The playbook notes there is no learned per-user id embedding in production retrieval (`phoenix/README.md`, `home-mixer/sources/phoenix_source.rs`). Personalization in that retriever is the history sequence, not a permanent user-id vector stored beside the account. The repository does not publish how many actions are in the sequence, or a command that empties it.

## What changing those inputs can and cannot do

Follows, blocks, mutes, and muted keywords are fields the hydrator reads. `AuthorSocialgraphFilter` drops an author the viewer has blocked or muted. `MutedKeywordFilter` drops a post that matches the viewer’s own muted keywords, including a hashtag keyword. Unfollowing removes that account from Thunder, which is the in-network source. Those are real code paths. They are not labeled “reset.”

Engagements you make after that become the next request’s main input. `not_interested` is a scoring head at −47.52, `mute_author` is −58.8, and `block_author` is −31.2 (`home-mixer/params/param.rs`). Those coefficients multiply a predicted probability for a post you are being shown. They are not a button that rebuilds your history.

`PreviouslySeenPostsFilter` uses an impression bloom filter plus an explicit seen-id set (`home-mixer/filters/previously_seen_posts_filter.rs`). A post shown once is not re-served. Clearing an app cache on your phone is not described in this repository, so this page does not claim that a reinstall empties that bloom filter.

`AgeFilter` drops posts older than 48 hours from For You. That is a cut on candidate age, not a reset of the viewer.

## What this page will not tell you to do

It will not list a seven-day mute ritual, a “like 20 posts in your niche” procedure, or a claim that the feed is clean after 48 hours. None of those procedures are in the tree. The code also does not say that logging out creates a new viewer embedding.

If the feed feels different in 2026, the published default changes are on [X algorithm changes in 2026](x-algorithm-changes-2026.md). Visibility drops that are not ranking at all are on [Shadowban on X](shadowban-on-x.md).

## Related

- [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)

## FAQ

### How do you reset the X algorithm?

You don’t, from this repository. Commit cb45b55 has no reset control. The next For You request is built from recent engagements, follows, blocks, mutes, muted keywords, seen posts, and followed topics. Changing a follow or a mute changes an input the hydrator reads. It does not publish a guarantee that the old history is gone.

### How do you reset the Twitter algorithm?

Same code. X is the product name on the repository. The Twitter-algorithm searches are the same For You pipeline. There is still no reset function in `home-mixer/`.

### Does clearing cache or waiting 48 hours reset For You?

The 48-hour figure in this tree is `AgeFilter` on posts, not a viewer-reset clock. Cache clearing is not specified. `PreviouslySeenPostsFilter` is a server-side bloom filter plus a seen-id set, and the repo does not say a client cache wipe clears it.

---

Source: https://docs.tweetfactory.sh/how-tweet-factory-scores-drafts.md

# How tweet-factory scores drafts

tweet-factory does not run Phoenix. It cannot know a hypothetical viewer’s predicted probabilities. After the model returns tweet text, `src/rank/score.ts` scores each variant on this machine. The 0–100 number is that local score.

The weights are the published defaults in `src/rank/weights.ts`, copied from [`xai-org/x-algorithm`](https://github.com/xai-org/x-algorithm) commit [`cb45b55`](https://github.com/xai-org/x-algorithm/commit/cb45b55). The same module builds `OPTIMIZER_SYSTEM` in `src/prompts/optimizer.ts`, so the prompt and the scorer share one table. The long write-up is [`X_ALGORITHM_BOOST_PLAYBOOK.md`](https://github.com/abhirupghosh/tweet-factory/blob/main/X_ALGORITHM_BOOST_PLAYBOOK.md). [The weights page](x-algorithm-engagement-weights.md) is the ranker. This page is the draft score.

## What `tf generate` asks for

`src/llm/generate.ts` builds one user message: your persona, measured voice stats, optional flush and Notion text, a calibration block from `tweets.db`, and an instruction to return JSON. The system prompt is `voiceSystem()` plus `OPTIMIZER_SYSTEM`. `voiceSystem()` ends with the style rules from `src/style/tells.ts` (no em dashes, no AI tells). Before scoring, every variant goes through the [style check](commands.md#style-check), so the score is computed on the rewritten text.

The default ask is 4 ideas (`DEFAULT_IDEA_COUNT`). `--n` changes that count. Each idea has 2 or 3 variants, aimed at different heads (copy-link share, reply, quote, or follow). The prompt tells the model to leave `score` at 0 and to post one variant per idea.

Zod accepts `ideas[]` (each variant has `text`, plus optional `aim` and `note`) or a legacy flat `drafts[]`. Any score in that object is discarded. `src/rank/bundle.ts` keeps at most 3 variants per idea, drops empty text, and sorts variants and ideas by the local score, then by weighted total. It writes a flat `drafts` array back with `text`, `score`, `signal` (the strongest positive head), and a note.

`onboarding.json` stores `ideas`, that `drafts` array, and `calibration` (`reliable`, `reason`, `window`).

Direct API calls use temperature 0.8 and a token cap of 8,000 so four ideas fit. The default backend is Claude Code (`claude -p --output-format json --tools ""`), with a 240 second timeout and no API key. Details are on [LLM providers](llm.md). Scraped tweets stay inside a reference fence, and the subprocess has no built-in tools.

## The 0–100 formula

For each head, the scorer assigns an editorial strength from 0 to 1, then multiplies by that head’s published weight. The weighted total is the sum of those contributions. It can go negative when a negative head fires.

The displayed score is that total divided by the sum of the positive weights in effect, times 100, rounded, and clamped to 0–100.

Text that does not start with `@` is treated as an original a mutual follow would see. Reply’s weight is then 20 (the published 5 plus the +15 mutual-original boost), and the positive-weight sum is 55.5. Text that starts with `@` is a reply: reply’s weight is 5, the format is `reply`, and the positive-weight sum is 40.5.

Author diversity (a second post from you in one viewer’s pool is ×0.625) and the 0.75 factor on out-of-network posts and on in-network replies/reposts are serving rules. They are not extra multipliers inside `scoreDraft`. The drafts file tells you to post one variant because of them. [How a For You request is built](how-the-x-algorithm-works.md) is where those factors are defined.

Heads in the local table, in the order the file prints them:

| Head | Published weight |
|---|---:|
| Copy-link share | 20 |
| Reply | 5, or 20 on a mutual original |
| DM share | 5 |
| Quote | 5 |
| Follow | 4 |
| Repost | 1 |
| Like | 0.5 |
| Report | −234 |
| Mute | −58.8 |
| Not interested | −47.52 |
| Block | −31.2 |

Dwell, click, open-link, photo expand, and video open are published ranker heads. They are not rows in this local score. The prompt says open-link is a small positive in the ranker (+0.2) and that a URL does not zero the post. Bookmarks are not a head.

Strengths come from the draft text. A specific question, and the word “you” or “your”, raises reply strength. “thoughts?”, “agree?”, “who agrees”, and “hot take?” count as a generic question and raise it much less. A first line of 40–200 characters with at least six words, and a digit, raise copy-link strength. A line break and a post of 12–70 words raise DM-share strength. First person raises follow strength. A digit and a post of 6–40 words raise repost strength. Like strength starts at 0.4 for any non-empty draft.

Engagement-bait phrases and rage words raise report, mute, or block strength. Three or more `#` characters raise report, mute, and not-interested strength, and six or more add more report strength. Under four words raises not-interested and lowers several positive strengths. A URL (`http`, `https`, or `t.co`) withholds a 0.1 copy-link bonus. It does not apply a fixed link penalty.

If report or mute strength is at least 0.05, the note says those weights dwarf a reply when that probability is not tiny. At a score of 70 or above, the note names the strongest positive head. Below 70, it names the weakest. The CLI keeps every variant. 70 is a label in the quip, not a filter.

`X_ALGORITHM_BOOST_PLAYBOOK.md` also prints a writing checklist (reply pull 24, quote/copy-link 22, and the rest of that 100-point table) and marks it **[heuristic]**. `tf generate` does not add those points. The number in `drafts/` is the per-head formula.

## Calibration from your own posts

`src/rank/calibrate.ts` computes the rates. `src/rank/calibrateDb.ts` reads rows with `source='own'` in `tweets.db`. It does not change the published weights. When the history is thick enough, it scales four strengths — reply, quote, repost, and like — by that format’s per-impression rate divided by the account-wide rate, clamped to 0.6–1.6. The product is clamped to 0–1 again.

- Fewer than 8 own posts with `impression_count > 0`: `reliable` is false, `window` is `none`, and every scale stays at 1. The file says scoring uses the published weights with no account adjustment.
- At least 8 of those posts older than 48 hours: rates use that settled window. 48 hours is the same span as `AgeFilter`.
- Fewer than 8 settled posts, but at least 8 posts with impressions: rates use every impressed post, including ones still inside the age gate (`window` `all`).
- A format is scaled only when the account is reliable and that format has at least 4 impressed posts. Format comes from `referenced_type`: reply, quote, repost, or original.
- Bookmarks are printed as a per-impression rate. They do not scale a head.
- Up to three of your posts with at least 100 impressions, the highest reply-per-impression first, are copied into the prompt (text cut to 140 characters) and labeled as examples not to copy.

`roast()` in `src/analyze.ts` calls `scoreDraft` with no calibration. `tf analyze` prints whether the history is thick enough to calibrate. `tf analyze --roast` scores recent posts with that same uncalibrated function and prints the calibration reason above them.

## The drafts file

`src/commands/generate.ts` writes `drafts/YYYY-MM-DD.md` through `src/rank/render.ts`. The header says to post one variant, quotes the ×0.625 second-post factor, names commit cb45b55, states the score definition, then prints the calibration reason and the bookmark note.

The shape, with sample figures (this is the file layout, not a measurement from an account):

```
# Drafts — YYYY-MM-DD

## the idea

### Variant 1 — score 72 — weighted 31.40
Aim: reply

the tweet

> why this variant

| Head | Strength | Weight | Contribution |
| Reply (mutual original, +15) | 0.82 | 20.0 | 16.40 |

Weighted total 31.40. Score 72/100. strongest head: reply (mutual original, +15).
```

When calibration moved a strength, a line under the table names the format and the reply, quote, repost, and like scales.

An optional skill at `~/.claude/skills/twitter-algorithm-optimizer/` can stand in for the playbook when a person runs that skill. `tf generate` does not load it. The binary scores with `src/rank/`.

## Browser checker

[tweetfactory.sh/score](https://tweetfactory.sh/score/) is a free page that reuses `src/rank/weights.ts` and the weighted sum in `src/rank/score.ts` (`rollup`). Its strengths are a separate heuristic for a pasted draft: a question or CTA raises reply, a number or a standalone first line raises copy-link and DM share, and hot-take wording raises mute and not-interested. Hashtags do not move it. A link adds `open_link` at +0.2 and does not subtract from the other heads. Toggles apply the out-of-network factor (0.75), the mutual-original reply boost, a media flag (`photo_expand` 0.05), and the second-post factor (0.625). Signed out, the draft stays in the browser. Sign in with X reads recent post metrics, scales those four heads with the same `calibratePosts` rates the CLI uses, and stores drafts you save. The page does not call a model. Details are on the [privacy page](https://tweetfactory.sh/privacy/).

## Related

- [How the X (Twitter) algorithm works](how-the-x-algorithm-works.md)
- [How to grow on X](x-algorithm-engagement-weights.md)
- [LLM providers](llm.md)

## FAQ

### How does tweet-factory score a draft?

`tf generate` asks your LLM for four ideas, each with two or three variants, and tells it to leave scores at 0. After Zod checks the JSON, `src/rank/score.ts` scores every variant. The CLI writes `drafts/YYYY-MM-DD.md` with a per-head table and writes `onboarding.json` with ideas, drafts, and calibration. The process does not call the X ranker.

### Does the score use the 2026 open-source weights?

The coefficients do. `src/rank/weights.ts` uses the published defaults from x-algorithm commit cb45b55: copy-link share 20, reply 5 (20 on an original a mutual follow sees), DM share 5, quote 5, follow 4, repost 1, like 0.5, and the four negative heads. The 0–1 strength beside each weight is an editorial read of the draft text. It is not Phoenix’s predicted probability for a viewer.

### What does a score of 70 mean?

70 is the quip threshold in `scoreDraft`. At or above it, the note names the strongest positive head. Below it, the note names the weakest. The CLI keeps drafts under 70. The number is 100 times the weighted total, divided by 55.5 for a mutual original or 40.5 for a reply, then rounded and clamped to 0–100.

### Is there a free tweet score calculator?

Yes. [tweetfactory.sh/score](https://tweetfactory.sh/score/) scores a pasted draft in the browser with the same published weights and the same weighted-sum function. It labels the result as a heuristic estimate. Signed out, it uses the published weights with no impression history. Sign in to scale reply, quote, repost, and like from recent posts and to save drafts. Install `tf` for voice-aware drafts from your own LLM.

### When does my own tweet history change the score?

When `tweets.db` has at least eight of your posts with impressions. Reply, quote, repost, and like strengths for a format are then multiplied by that format’s per-impression rate divided by the account-wide rate, and clamped between 0.6 and 1.6, if that format has at least four impressed posts. Posts older than 48 hours are preferred once eight of them exist. Bookmarks are printed and do not scale a head. Fewer than eight impressed posts leaves every scale at 1. On [tweetfactory.sh/score](https://tweetfactory.sh/score/), the same rate math runs after you sign in with X, using recent posts from the X API.

---

Source: https://docs.tweetfactory.sh/what-is-tweepcred.md

# What is TweepCred

**Last updated 2026-10-11.** A search of [`xai-org/x-algorithm`](https://github.com/xai-org/x-algorithm) at commit [`cb45b55`](https://github.com/xai-org/x-algorithm/commit/cb45b55) finds no file, comment, or identifier named TweepCred. This page will not invent a calculator for a name that is not in the tree, and it will not copy constants from an older repository this site has not re-read.

People still use the word for “a hidden author reputation score.” The current tree has a different job, with a different name, and it is not wired into the For You sum.

## What the current code publishes instead

`user-cred-v2/` is the account-scoring job. The README’s August 13, 2026 section lists it among models that score accounts on various dimensions, next to Agatha and BDSM, in the group of systems that can feed visibility labels. The package is `com.twitter.health.platform_manipulation.user_cred_v2`.

What that job actually computes, from the Scala in that directory:

- It runs a PageRank-style iteration (`pageRankMain`) over follow edges, after dropping users who are restricted, deactivated, suspended, or erased (`ValidUserInfo.fromFlatUser`).
- Engagement edges are favorites and reposts (`InteractionType.Favorite` and `InteractionType.Retweet`) inside `EngagementWindowDays` = 7. Edges between linked accounts from the account-expansion dataset are removed.
- The teleport mix (`computeTeleportWeights`) blends two distributions with `engagement_teleport_beta`, default `0.5`. One side is uniform over accounts whose `isPremium` is true (blue, gray, gold, verified organization, or affiliate). The other side is those engagement edges, weighted by the engager’s prior mass.
- Default PageRank arguments in `UserCredV2Config.fromArgs` are jump probability `0.2`, difference threshold `0.001`, and max iterations `50`. Those are argument defaults, not a measured reputation of any account.
- `UserCredV2.fromMass` turns mass into a score: 0 when mass is ≤ 0, otherwise `165.2 + 7.07 * ln(mass)`, clamped to 0–100.

A warm start reads the previous mass snapshot no older than 7 days. If a previous mass exists for that id, `joinPreviousMass` keeps the previous mass rather than the fresh one.

## What it does not do

`home-mixer/` does not reference `UserCredV2`. `visibility-filtering/` does not either. The published For You weights in `home-mixer/params/param.rs` have no TweepCred column and no user-cred column. Premium is not a term in that sum. The premium flag above is only the uniform teleport set inside `user-cred-v2`.

So a TweepCred-style number, even under the new name, is not something this commit multiplies into a post’s For You score. The README says the job can matter to visibility labels. The code that would read `UserCredV2` from inside `visibility-filtering/` is not in this commit, so this page does not claim a specific label or a drop threshold.

SimClusters jobs mention a dataset named `entityRealGraph`. That is a graph input to embedding jobs. It is not TweepCred, and it is not a head in `compute_weighted_score`.

## If you wanted a number on a draft

A draft score and an author-reputation score are different objects. tweet-factory’s draft score uses the published action weights and is described on [How tweet-factory scores drafts](how-tweet-factory-scores-drafts.md). The browser draft score is [tweetfactory.sh/score](https://tweetfactory.sh/score/). It is not a TweepCred calculator, because the current ranker does not publish one.

## Related

- [How the X (Twitter) algorithm works](how-the-x-algorithm-works.md)
- [Twitter algorithm on GitHub](twitter-algorithm-github.md)
- [How to grow on X](x-algorithm-engagement-weights.md)

## FAQ

### What is TweepCred?

In commit cb45b55, it is a name that does not occur. The account-scoring program in that tree is `user-cred-v2`: a PageRank over follows, with a teleport that mixes premium accounts and seven days of likes and reposts, then a 0–100 score from `165.2 + 7.07 * ln(mass)`.

### Does TweepCred change the For You score?

Not under that name, and not as `UserCredV2` either. The weighted sum does not read it. `home-mixer` and `visibility-filtering` contain no reference to the type. Premium is not an organic ranking bonus in `param.rs`.

### Can I calculate my TweepCred from this repo?

No. The job needs production datasets (follows, server engagements, user snapshots) that are not in the GitHub checkout, and the For You request path does not consume the output. This site does not ship a TweepCred calculator on top of a missing input.

---

Source: https://docs.tweetfactory.sh/twitter-algorithm-github.md

# Twitter algorithm on GitHub: the-algorithm (2023) and x-algorithm (2026)

**Last updated 2026-10-21.** “Twitter algorithm GitHub” points at two repositories. Twitter published [`twitter/the-algorithm`](https://github.com/twitter/the-algorithm) in March 2023: the Twitter-era recommendation services, mostly Scala and Java, with the model code in [`twitter/the-algorithm-ml`](https://github.com/twitter/the-algorithm-ml). The code behind the X For You feed in 2026 is [`xai-org/x-algorithm`](https://github.com/xai-org/x-algorithm), and that is the repo this page maps. This walkthrough is commit [`cb45b55`](https://github.com/xai-org/x-algorithm/commit/cb45b55) (2026-10-09). It follows the repo `README.md` and the file citations in [`X_ALGORITHM_BOOST_PLAYBOOK.md`](https://github.com/abhirupghosh/tweet-factory/blob/main/X_ALGORITHM_BOOST_PLAYBOOK.md). It is a map, not a second ranker.

## What the README says the repo is

The For You feed is assembled per request. In-network posts come from `thunder/`. Out-of-network posts come from `phoenix/` retrieval, `simclusters/`, and `home-mixer/sources/popular_posts_source.rs`. The same model ranks both. Phoenix reads the viewer’s recent engagements and predicts an action probability per post. Weights in the code blend those predictions. A separate blending pipeline adds ads, Who to Follow, and prompts, which the model does not rank.

Ranking sets order. Whether a post can be shown is `visibility-filtering/`.

## Where to read each stage

| Stage | Path the README and the playbook cite |
|---|---|
| Request order | `home-mixer/candidate_pipeline/phoenix_candidate_pipeline.rs` |
| Query hydration | `home-mixer/query_hydrators/` |
| In-network store | `thunder/`, caps in `thunder/config.rs` |
| Out-of-network retrieval | `phoenix/`, source `home-mixer/sources/phoenix_source.rs` |
| Clusters | `simclusters/`, source `home-mixer/sources/simclusters_source.rs` |
| Popular list | `home-mixer/sources/popular_posts_source.rs` |
| Pre-score filters | `home-mixer/filters/` |
| Weighted sum | `xai-value-model/scoring.rs`, defaults in `home-mixer/params/param.rs` |
| Served recompute | `vm-ranker/`, including `vm-ranker/dpp.rs` and `vm-ranker/params.rs` |
| Visibility | `visibility-filtering/rules/registry.rs` |
| Training code | `phoenix/` (Cargo workspace, `pyproject.toml`, `phoenix/QUICKSTART.md`) |

`Tweet Mixer` and the SID source are in the tree and default off. The playbook records `PhoenixMaxResults` 1000, `ThunderMaxResults` 1200, top-50 selection, and a served `RESULT_SIZE` of 35. Those numbers are in [How the X (Twitter) algorithm works](how-the-x-algorithm-works.md).

## What GitHub does not include

The README section “What’s not in this repo?” says the Grox classifier prompts are not shipped. The playbook repeats that: Jinja templates are loaded by name from `grox/flows/ptos/prompts.py` and `grox/flows/upa/prompts.py`, and the prompt bodies are absent. Trained Phoenix weights are also absent. A default of `0.0` on a head means off in the mirrored primary config, not “the head was deleted.”

`phoenix/run_pipeline.py`, the old demo that used favorite 1.0 and reply 0.5, is not in this commit. The August 13, 2026 README release replaced that demonstration model with training code and the published weights.

The string `TweepCred` does not appear in this commit. The account-scoring job that does exist is `user-cred-v2/`, covered on [What is TweepCred](what-is-tweepcred.md).

## How tweet-factory uses the repo

tweet-factory does not run this pipeline. `src/rank/weights.ts` copies the published probability weights and the negative heads, and `tf generate` multiplies those by an editorial strength. The GitHub tree remains the source for the coefficients. A browser pass over one draft is [tweetfactory.sh/score](https://tweetfactory.sh/score/).

## Related

- [How the X (Twitter) algorithm works](how-the-x-algorithm-works.md)
- [X algorithm changes in 2026](x-algorithm-changes-2026.md)
- [Shadowban on X](shadowban-on-x.md)

## FAQ

### Where is the Twitter algorithm on GitHub?

Two places. The 2023 Twitter release is [`twitter/the-algorithm`](https://github.com/twitter/the-algorithm), with models in [`twitter/the-algorithm-ml`](https://github.com/twitter/the-algorithm-ml). The current X code is [`xai-org/x-algorithm`](https://github.com/xai-org/x-algorithm), commit `cb45b55` as of this page. For You order is `home-mixer/candidate_pipeline/phoenix_candidate_pipeline.rs`. Weights are `home-mixer/params/param.rs`. Visibility rules are `visibility-filtering/rules/registry.rs`.

### Is the Twitter algorithm open source?

Mostly. The ranking code is public on GitHub: `twitter/the-algorithm` since March 2023 and `xai-org/x-algorithm` for the current X feed. The `xai-org/x-algorithm` README says the Grox classifier prompts are not shipped, and the trained Phoenix weights are not in the checkout either.

### What is the difference between twitter/the-algorithm and xai-org/x-algorithm?

`twitter/the-algorithm` is the March 2023 Twitter release, built around services such as `home-mixer`, `simclusters-ann`, and `visibilitylib`, mostly in Scala and Java. `xai-org/x-algorithm` is the code X publishes for the For You feed today, with `thunder/`, `phoenix/` retrieval and ranking, and the weights in `home-mixer/params/param.rs`. To check what affects reach now, read `xai-org/x-algorithm`.

### Can you run the whole ranker from the GitHub checkout?

The README says Phoenix is meant to be trainable end to end, with a quickstart and synthetic data. It also says other directories may omit build files. The Grox prompts and the trained production weights are not in the checkout, so a local Phoenix run is not a reproduction of the live For You score.

---

Source: https://docs.tweetfactory.sh/ai-tweet-writer-your-voice.md

# Tweet generator in your voice

tweet-factory is a local private tweet generator and an AI tweet generator that writes in one account’s voice. It is a Bun and TypeScript CLI, `tf`. All rights reserved. Source: [abhirupghosh/tweet-factory](https://github.com/abhirupghosh/tweet-factory). It runs on the machine where you install it. Likes, bookmarks, and your posts go into `tweets.db`. Drafts go into `drafts/`. You publish them yourself. Local files stay the default. Optional cloud sync copies that checkout only after `tf login` and `tf sync push`.

People also search “AI tweet writer” and “AI tweet generator that sounds like me.” Those match this CLI only because the voice comes from your own posts and the model is one you already run. It is not a hosted scheduler, and it is not a claim that the drafts will rank. Claude Code is the default backend; the setup is on [Using tweet-factory with Claude Code](claude-code-twitter.md).

## Where the voice comes from

`src/prompts/voice.ts` builds the system prompt from two files of your data:

- `persona/PERSONA.md`, if it exists. The comment in that module calls it the source of truth for voice. `tf onboard` can write it. You can also edit the template.
- Measured stats from `tweets.db`: the share of posts that start lowercase, the median word count, recurring markers, and the accounts you engage with most.

The instruction in that prompt is to match casing, length, phrasing, and stance, and not to flatten the voice into generic copy. Notion pages you tag, and the flush of new likes and bookmarks, can be attached as fenced reference data. The prompt tells the model that text is data, not instructions.

If there is no persona file yet, the same function says to infer voice from the measured signals.

## Claude Code, or another provider

The default provider is `claude-code`. `src/llm/claudecode.ts` spawns:

```
claude -p <prompt> --output-format json --tools "" --disallowedTools "*,mcp__*" --permission-mode dontAsk
```

No API key is read for that path. It uses the `claude` login already on the machine. `--tools ""` removes built-in tools, so a tweet in the reference data cannot make it run a shell. If `claude` is not on `PATH`, the error tells you to install Claude Code or set `TF_LLM_PROVIDER` and a key.

The other providers, from `src/llm/provider.ts`:

| `TF_LLM_PROVIDER` | Key | Default model in code |
|---|---|---|
| `claude-code` | none | the CLI’s own default |
| `anthropic` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` |
| `openrouter` | `OPENROUTER_API_KEY` | `anthropic/claude-sonnet-4.6` |
| `openai` | `OPENAI_API_KEY` | `gpt-4o` |

Direct API calls use temperature 0.8. Claude Code gets a 240 second timeout. More on the [LLM providers](llm.md) page.

## What it will not do

OAuth scopes in `src/x/auth.ts` are `tweet.read`, `users.read`, `like.read`, `bookmark.read`, and `offline.access`. There is no write scope and no command that creates a post. `tf notify` posts a file to Slack when a webhook is set. Publishing on X is a step you take outside `tf`.

The 0–100 number on a draft is computed after the model returns text. `src/rank/score.ts` multiplies an editorial strength on each head by the published weight in `src/rank/weights.ts` (x-algorithm commit cb45b55). It is a local heuristic, not a live For You rank. [How scoring works](how-tweet-factory-scores-drafts.md) has the formula, the four-idea shape, and the calibration rules.

Install the release binary from [Install](install.md). A checkout can still build with `./setup_x.sh`. A coding agent can follow [the runbook](agent.md).

## Related

- [Install](install.md)
- [How the X algorithm works](how-the-x-algorithm-works.md)
- [Compared with Typefully, Tweet Hunter, and Hypefury](compare-typefully-tweet-hunter-hypefury.md)

## FAQ

### What is a tweet generator that uses my own posts?

`tf generate` is that generator. It sends `persona/PERSONA.md` and measured stats from `tweets.db` to your LLM and writes four ideas, each with two or three variants, to `drafts/YYYY-MM-DD.md`. The 0–100 number is filled in locally after the model returns text. You post the variant you want.

### Is there a private tweet generator that runs on your machine?

tweet-factory is proprietary. All rights reserved. Source is at github.com/abhirupghosh/tweet-factory. `tf fetch` stores your X activity in SQLite on that machine. `tf generate` writes drafts to `drafts/YYYY-MM-DD.md`. Nothing in the CLI creates an X post.

### Can Claude Code write the tweets?

Yes, as the default backend. `tf` runs `claude -p` with your existing Claude Code login and with tools disabled. Set `TF_LLM_PROVIDER` to `anthropic`, `openrouter`, or `openai` if you want a direct API instead. You still publish the draft yourself.

### Will the drafts sound like me and rank on For You?

The voice prompt is your persona file plus stats from your own posts, likes, and bookmarks. That is a writing constraint. The score beside a draft is the local per-head heuristic in `src/rank/score.ts`, using the published weights, with a calibration from your impressions when at least eight of your posts have them. The open-source ranker is a different system, described on [the algorithm page](how-the-x-algorithm-works.md). This CLI does not execute it.

---

Source: https://docs.tweetfactory.sh/claude-code-twitter.md

# Using tweet-factory with Claude Code

**Last updated 2026-10-11.** “Claude Code Twitter” here means using the Claude Code CLI as the model that drafts posts. tweet-factory’s default provider is `claude-code`. It does not send your likes to a tweet-factory server, and it does not create the post on X.

## What the process runs

`src/llm/claudecode.ts` spawns:

```
claude -p <prompt> --output-format json --tools "" --disallowedTools "*,mcp__*" --permission-mode dontAsk
```

No API key is read on that path. The command uses the `claude` login already on the machine. `--tools ""` removes built-in tools, so a tweet, article, or Notion page inside the prompt cannot make it run a shell. If `claude` is missing, the error tells you to install Claude Code or set `TF_LLM_PROVIDER` and a key. The timeout is 240 seconds. `TF_LLM_MODEL` is passed as `claude --model` when you set it.

The prompt is `voiceSystem()` from `persona/PERSONA.md` and measured stats, plus `OPTIMIZER_SYSTEM` built from `src/rank/weights.ts`. Scraped text is fenced as reference data. The model is told to return JSON and to leave scores at 0. After it returns, `src/rank/score.ts` fills the 0–100 number. See [the tweet generator](ai-tweet-writer-your-voice.md) and [how drafts are scored](how-tweet-factory-scores-drafts.md).

## A run that stays on your machine

```bash
tf auth
tf fetch
tf onboard
tf generate
```

`tf generate` writes `drafts/YYYY-MM-DD.md` and `onboarding.json`. Default shape: four ideas, two or three variants each. `--n` changes the idea count. `--json` prints the bundle. You publish the variant you want. OAuth scopes in `src/x/auth.ts` are `tweet.read`, `users.read`, `like.read`, `bookmark.read`, and `offline.access`. There is no write scope.

Claude Code has to be logged in on that machine, including a server you cron from. `tf` does not ship a Claude credential.

## The optional Claude Code skill

The repo includes `.claude/skills/tweet-factory/SKILL.md`, triggered as `/tweet-factory` inside Claude Code. That skill calls `tf` for fetch, flush, and data, then drafts. It is optional. `tf generate` does not load it. An extra skill at `~/.claude/skills/twitter-algorithm-optimizer/` can replace the playbook when a person runs the skill. The binary still scores with `src/rank/weights.ts`.

Direct APIs, if you would rather not use Claude Code, are `TF_LLM_PROVIDER=anthropic`, `openrouter`, or `openai`. Temperature is 0.8 and the token cap is 8,000. Details are on [LLM providers](llm.md).

## Related

- [Tweet generator in your voice](ai-tweet-writer-your-voice.md)
- [Install](install.md)
- [LLM providers](llm.md)

## FAQ

### Can Claude Code write tweets?

Yes, as tweet-factory’s default backend. `tf generate` runs `claude -p` with your existing Claude Code login and with tools disabled. The output is a local markdown file. You post it.

### Does Claude Code post to Twitter or X for me?

No. The CLI’s X scopes are read-only. Claude Code is the language model, not an X client. Publishing stays outside `tf`.

### Do I need an Anthropic API key?

Not for the default path. The default uses the `claude` CLI login. Set `ANTHROPIC_API_KEY` only if you switch `TF_LLM_PROVIDER` to `anthropic`.

---

Source: https://docs.tweetfactory.sh/compare-typefully-tweet-hunter-hypefury.md

# tweet-factory vs Typefully, Tweet Hunter, and Hypefury

These products show up next to “tweet generator.” They are not the same kind of software. tweet-factory is a local CLI that drafts and stops. The other three, on their own public pages, are hosted apps that schedule and publish.

Each product has its own page: [Typefully alternative](typefully-alternative.md), [Tweet Hunter alternative](tweet-hunter-alternative.md), [Hypefury alternative](hypefury-alternative.md). The table below is the same 2026-10-10 fetch, kept in one place.

Facts about tweet-factory come from this repository. Facts about the other three come from pages fetched on 2026-10-10. Marketing totals (customer counts, impression totals) are left out. Prices are quoted only where the HTML stated a number. Paid tiers that render only in the browser are not guessed.

## What each site says it is

**tweet-factory** ([tweetfactory.sh](https://tweetfactory.sh/), [source](https://github.com/abhirupghosh/tweet-factory)). A Bun CLI. OAuth scopes in `src/x/auth.ts` are `tweet.read`, `users.read`, `like.read`, `bookmark.read`, and `offline.access`. `tf generate` writes a markdown file and `onboarding.json`. There is no command that creates a post. All rights reserved. The software’s listed price in the landing-page schema is 0. If you set `TF_LLM_PROVIDER` to a direct API, you pay that provider. Claude Code, the default, uses the `claude` login already on the machine.

**Typefully** ([typefully.com](https://typefully.com/)). The homepage describes an AI-powered collaborative scheduler for X, LinkedIn, Bluesky, and Threads, and the cross-post line also names Mastodon. It says the product publishes, previews threads before they go live, and that its AI learns how you write in order to brainstorm, rewrite, and expand. The same page lists a free plan, a Mac app, a calendar, analytics, Auto-Plug and Auto-RT, and a free API. The pricing page’s static HTML (`https://typefully.com/pricing`, title “Pricing | Typefully”) did not include dollar amounts, so this page does not invent them. The homepage is a sign-up product (Google, X, LinkedIn, or email). Their site does not present the product as a local private CLI.

**Tweet Hunter** ([tweethunter.io](https://tweethunter.io/)). The homepage describes writing and scheduling for X, analytics, and automation it names as Auto DM, retweet, and plug. It also describes an AI writing pass and a library of other people’s tweets to take inspiration from. The pricing document’s `<title>` is “Tweet Hunter Pricing - Plans from $49/mo | Try Free for 7 Days”, and the meta description says the product is “AI-powered writing, scheduling, analytics, and CRM for X (Twitter).” A public OAuth URL on the homepage requests `tweet.write` and `dm.write` among other scopes (`redirect_uri` on `app.tweethunter.io`). That is a write-capable login. This page does not repeat the homepage’s library-size figures, because the same page states more than one number.

**Hypefury** ([hypefury.com](https://hypefury.com/)). The homepage describes scheduling and automation across X, LinkedIn, Instagram, Bluesky, Threads, TikTok, and an email list. It says the AI learns from your posts and generates posts that sound like you, and it names auto-plugs, Auto-DM, auto reposts, and evergreen posts. The pricing page’s meta description says “one simple pricing plan: $6/month or $5/month if billed yearly.” The body says “6 USD/month for each additional platform.” The FAQ answer on that page says they no longer offer a free plan, and that a 7-day trial is available on the Starter plan. Those three sentences are all on `https://hypefury.com/pricing`. This page does not collapse them into one number.

## Side by side

| | tweet-factory | Typefully | Tweet Hunter | Hypefury |
|---|---|---|---|---|
| Where it runs | Your machine. SQLite file `tweets.db`. | Hosted. Sign-up on the homepage. | Hosted. App host `app.tweethunter.io` in the public OAuth URL. | Hosted. Sign-up on the homepage. |
| Source you can read | Private. All rights reserved. | Not offered as a local source repo on the pages above. | Same. | Same. |
| Creates X posts | No. Read scopes only. You publish. | Homepage says it publishes and schedules, including cross-posting. | Homepage says it schedules posts. OAuth URL requests `tweet.write`. | Homepage says it schedules posts and can auto-plug and auto-repost. |
| Voice | `persona/PERSONA.md` plus stats from your posts, likes, and bookmarks. Your model. | Homepage: AI that learns how you write, inside their editor. | Homepage: personalized suggestions and rewrites. | Homepage: AI learns from your posts. |
| Networks named on the homepage | X, read-only. | X, LinkedIn, Bluesky, Threads, and Mastodon in the cross-post line. | X. | X, LinkedIn, Instagram, Bluesky, Threads, TikTok, email. |
| Price, as published that day | Software price 0. API models are billed by that vendor. | A free plan is named. Paid prices were not in the static pricing HTML. | Title: plans from $49/mo. 7-day trial. | Meta: $6/mo or $5/mo yearly. FAQ: no free plan, 7-day Starter trial. Extra platform line: 6 USD/mo. |

## What this does not decide

Nothing here measures whose drafts get more impressions. The open-source ranker does not contain a scheduler head, and this repo has not run a comparison study. [How the X (Twitter) algorithm works](how-the-x-algorithm-works.md) is the ranker. [How tweet-factory scores drafts](how-tweet-factory-scores-drafts.md) is a local heuristic on the published weights. It is not a live For You rank.

If you want a team calendar, cross-posting, or a product that publishes for you, the hosted tools say they do that. If you want the drafts and the database to stay in a git checkout, and you are willing to post yourself, that is the CLI.

## Related

- [An AI writer in your voice](ai-tweet-writer-your-voice.md)
- [Install](install.md)
- [Security](security.md)

## FAQ

### Is tweet-factory a replacement for Typefully, Tweet Hunter, or Hypefury?

Only for the drafting step, and only if you want that step on your own machine. Those three describe themselves as hosted schedulers that publish. tweet-factory’s OAuth scopes do not include `tweet.write`, and the CLI has no post command. Scheduling, team review, and cross-posting are features their pages list and this repo does not implement.

### Which one runs on your machine?

tweet-factory is proprietary and runs on your machine. All rights reserved. Source is at github.com/abhirupghosh/tweet-factory. The Typefully, Tweet Hunter, and Hypefury pages fetched on 2026-10-10 describe hosted apps you sign up for. Those pages do not link a public source tree for the product.

### Do any of them guarantee For You reach?

No page in this set, including ours, is a measurement of reach. tweet-factory’s draft score is computed locally from published weights after the model returns text. The For You coefficients live in the open-source ranker and are easy to misread as multipliers on like counts. They are not. See [how to grow on X](x-algorithm-engagement-weights.md).

---

Source: https://docs.tweetfactory.sh/typefully-alternative.md

# Typefully alternative

**Fetched 2026-10-10.** This page is a Typefully alternative only for the drafting step, and only if that step should stay on your machine. It uses tweet-factory’s source and Typefully’s public pages from that day. It does not invent prices or reach numbers.

## What Typefully’s pages said

[typefully.com](https://typefully.com/) described an AI-powered collaborative scheduler for X, LinkedIn, Bluesky, and Threads. The cross-post line also named Mastodon. The page said the product publishes, previews threads before they go live, and that its AI learns how you write in order to brainstorm, rewrite, and expand. It listed a free plan, a Mac app, a calendar, analytics, Auto-Plug and Auto-RT, and a free API. Sign-up on the homepage is Google, X, LinkedIn, or email.

The pricing page’s static HTML (`https://typefully.com/pricing`, title “Pricing | Typefully”) did not include dollar amounts. This page does not guess them. Those pages did not link a public source tree for the product.

## What tweet-factory is instead

[tweetfactory.sh](https://tweetfactory.sh/) is a local private Bun CLI that runs on your machine. All rights reserved. Source: [abhirupghosh/tweet-factory](https://github.com/abhirupghosh/tweet-factory). OAuth scopes in `src/x/auth.ts` are `tweet.read`, `users.read`, `like.read`, `bookmark.read`, and `offline.access`. `tf generate` writes `drafts/YYYY-MM-DD.md` and `onboarding.json`. There is no command that creates a post. The landing-page schema lists the software price as 0. A direct API provider is billed by that provider. Claude Code, the default, uses the `claude` login already on the machine. Voice is `persona/PERSONA.md` plus stats from your posts, likes, and bookmarks.

| | tweet-factory | Typefully, on 2026-10-10 |
|---|---|---|
| Where it runs | Your machine. SQLite file `tweets.db`. | Hosted. Sign-up on the homepage. |
| Source | Private. All rights reserved. | Not offered as a local source repo on the pages above. |
| Creates X posts | No. Read scopes only. | Homepage says it publishes and schedules, including cross-posting. |
| Networks named | X, read-only. | X, LinkedIn, Bluesky, Threads, and Mastodon in the cross-post line. |
| Price as published | Software price 0. | A free plan is named. Paid prices were not in the static pricing HTML. |

Nothing here measures whose drafts get more impressions. The open-source ranker has no scheduler head. [How the X (Twitter) algorithm works](how-the-x-algorithm-works.md) is the ranker. [How drafts are scored](how-tweet-factory-scores-drafts.md) is the local heuristic.

The same fetch is split for [Tweet Hunter](tweet-hunter-alternative.md) and [Hypefury](hypefury-alternative.md). The three-way table is still on [the comparison hub](compare-typefully-tweet-hunter-hypefury.md).

## Related

- [Tweet generator in your voice](ai-tweet-writer-your-voice.md)
- [Tweet Hunter alternative](tweet-hunter-alternative.md)
- [Hypefury alternative](hypefury-alternative.md)

## FAQ

### Is tweet-factory a Typefully alternative?

For local drafting, yes. For scheduling, team review, cross-posting, or a product that publishes, no. Typefully’s homepage says it publishes. tweet-factory’s scopes do not include `tweet.write`.

### Is there a local Typefully alternative that runs on your machine?

tweet-factory is proprietary and runs on your machine. All rights reserved. Source is at github.com/abhirupghosh/tweet-factory. The Typefully pages fetched on 2026-10-10 describe a hosted app and do not link a public source tree.

### Does either one guarantee For You reach?

No. tweet-factory’s draft score is a local heuristic on published weights. It is not a live rank. Typefully’s pages from that day are not an impression study.

---

Source: https://docs.tweetfactory.sh/tweet-hunter-alternative.md

# Tweet Hunter alternative

**Fetched 2026-10-10.** This page compares tweet-factory with Tweet Hunter using source in this repo and pages fetched that day. Marketing totals and library-size figures are left out, because the homepage stated more than one library number.

## What Tweet Hunter’s pages said

[tweethunter.io](https://tweethunter.io/) described writing and scheduling for X, analytics, and automation it names as Auto DM, retweet, and plug. It also described an AI writing pass and a library of other people’s tweets to take inspiration from. The pricing document’s `<title>` is “Tweet Hunter Pricing - Plans from $49/mo | Try Free for 7 Days”. The meta description says the product is “AI-powered writing, scheduling, analytics, and CRM for X (Twitter).”

A public OAuth URL on the homepage requests `tweet.write` and `dm.write` among other scopes, with `redirect_uri` on `app.tweethunter.io`. That is a write-capable login. Those pages did not present the product as a local private CLI.

## What tweet-factory is instead

tweet-factory drafts on your machine and stops. Scopes in `src/x/auth.ts` are `tweet.read`, `users.read`, `like.read`, `bookmark.read`, and `offline.access`. There is no `tweet.write` and no `dm.write`. `tf generate` writes a markdown file. Voice comes from `persona/PERSONA.md` and from your own likes, bookmarks, and posts, not from a library of other people’s tweets. All rights reserved. The software price in the landing schema is 0.

| | tweet-factory | Tweet Hunter, on 2026-10-10 |
|---|---|---|
| Where it runs | Your machine. `tweets.db`. | Hosted. App host `app.tweethunter.io` in the public OAuth URL. |
| Source | Private. All rights reserved. | Not offered as a local source repo on the pages above. |
| Creates X posts | No. | Homepage says it schedules posts. OAuth URL requests `tweet.write`. |
| Voice | Your persona file and your own activity. Your model. | Homepage: personalized suggestions and rewrites. |
| Price as published | Software price 0. | Title: plans from $49/mo. 7-day trial. |

[Typefully](typefully-alternative.md) and [Hypefury](hypefury-alternative.md) are separate pages from the same fetch. Ranker behavior is [How the X (Twitter) algorithm works](how-the-x-algorithm-works.md), not a feature of either product.

## Related

- [Tweet generator in your voice](ai-tweet-writer-your-voice.md)
- [Typefully alternative](typefully-alternative.md)
- [Comparison hub](compare-typefully-tweet-hunter-hypefury.md)

## FAQ

### Is tweet-factory a Tweet Hunter alternative?

For drafting in your own files, yes. For scheduling, Auto DM, or a login that can write posts, no. Tweet Hunter’s public OAuth URL requests `tweet.write` and `dm.write`. tweet-factory does not.

### How much does Tweet Hunter cost?

The pricing page title fetched on 2026-10-10 says plans from $49/mo and a 7-day trial. This page does not add tiers that were not in that title.

### Which one runs on your machine?

tweet-factory is proprietary and runs on your machine. All rights reserved. Source is at github.com/abhirupghosh/tweet-factory. The Tweet Hunter pages from that day describe a hosted app and do not link a public source tree.

---

Source: https://docs.tweetfactory.sh/hypefury-alternative.md

# Hypefury alternative

**Fetched 2026-10-10.** This page compares tweet-factory with Hypefury using this repo and Hypefury’s public pages from that day. The pricing page states three different money sentences. They are quoted separately and not collapsed into one price.

## What Hypefury’s pages said

[hypefury.com](https://hypefury.com/) described scheduling and automation across X, LinkedIn, Instagram, Bluesky, Threads, TikTok, and an email list. It said the AI learns from your posts and generates posts that sound like you, and it named auto-plugs, Auto-DM, auto reposts, and evergreen posts.

On `https://hypefury.com/pricing`:

- The meta description says “one simple pricing plan: $6/month or $5/month if billed yearly.”
- The body says “6 USD/month for each additional platform.”
- The FAQ says they no longer offer a free plan, and that a 7-day trial is available on the Starter plan.

Those pages describe a hosted sign-up product. They do not link a public source tree.

## What tweet-factory is instead

tweet-factory is a local private CLI. It runs on your machine. It reads X and writes drafts. It does not schedule, cross-post, or send DMs. Scopes stop at `tweet.read`, `users.read`, `like.read`, `bookmark.read`, and `offline.access`. The software price in the landing schema is 0. You publish.

| | tweet-factory | Hypefury, on 2026-10-10 |
|---|---|---|
| Where it runs | Your machine. | Hosted. Sign-up on the homepage. |
| Source | Private. All rights reserved. | Not offered as a local source repo on the pages above. |
| Creates X posts | No. | Homepage says it schedules posts and can auto-plug and auto repost. |
| Networks named | X, read-only. | X, LinkedIn, Instagram, Bluesky, Threads, TikTok, email. |
| Price as published | Software price 0. | Meta: $6/mo or $5/mo yearly. Extra platform: 6 USD/mo. FAQ: no free plan, 7-day Starter trial. |

[Typefully](typefully-alternative.md) and [Tweet Hunter](tweet-hunter-alternative.md) are the other two pages. None of the three, and not tweet-factory, is an impression study. The ranker is [How the X (Twitter) algorithm works](how-the-x-algorithm-works.md).

## Related

- [Tweet generator in your voice](ai-tweet-writer-your-voice.md)
- [Typefully alternative](typefully-alternative.md)
- [Tweet Hunter alternative](tweet-hunter-alternative.md)

## FAQ

### Is tweet-factory a Hypefury alternative?

For local drafts in your voice, yes. For multi-network scheduling, auto-plugs, Auto-DM, or evergreen reposts, no. Those are features Hypefury’s homepage names and this repo does not implement.

### How much does Hypefury cost?

Three sentences from the pricing page on 2026-10-10, kept separate: meta description “$6/month or $5/month if billed yearly”; body “6 USD/month for each additional platform”; FAQ “no free plan” and a 7-day Starter trial.

### Does the AI that learns your voice also post?

Hypefury’s homepage says its AI learns from your posts and that the product schedules. tweet-factory’s model also learns from your posts, and the CLI stops at the draft file.