waybetter-for-x/README.md

<p align="center"><img src="assets/readme/hero.webp" width="880" alt="wayBetter for X: the deck, three of your accounts side by side in one window"></p>

<h1 align="center">wayBetter for X</h1>

<p align="center"><b>X, the way it should work.</b> The real x.com in a light desktop app: tabs, split panes,
every account side by side, themes, plugins, and fixes for the bugs X ships.<br>
Free and open source (GPL-3.0-or-later). No ads, no paid tier, no telemetry.</p>

<p align="center"><a href="https://waybetter.fyi/x/"><b>Download</b></a> ·
<a href="https://waybetter.fyi/store/">Store</a> ·
<a href="docs/THEMES.md">Make a theme</a> ·
<a href="docs/PLUGINS.md">Write a plugin</a> ·
<a href="https://git.crt.fyi/CRT/waybetter">The framework</a> ·
<a href="CHANGELOG.md">Changelog</a></p>

wayBetter for X is not a new X client. It opens X's own website in a small native window (Tauri 2,
one system WebView per tab) and changes it in place, in your window only, the way BetterDiscord
extends Discord. It runs on macOS, Windows and Linux, and it is the first app built on
[wayBetter](https://git.crt.fyi/CRT/waybetter), a framework for doing the same to other sites.
It is an independent project, not affiliated with, endorsed by or sponsored by X Corp.

## Why

### It fixes what X won't

Click Like eight times, fast. The clicks cancel out, so the post should end up not liked. In a
browser X still shows a like; in wayBetter the heart, the count and the server agree. The same fix
covers repost, bookmark and follow.

![Eight clicks on Like: X in Safari ends showing 1 like, wayBetter ends at 0, like the server](assets/readme/like-fix.webp)

### Unlimited accounts, all signed in

Drag a tab to the edge to split. Each account lives in its own profile and stays signed in, so all of
them sit side by side in one window. You log in on x.com itself, the normal way.

![A new tab: open X as any of your signed-in accounts, with Home, Notifications, Messages, Bookmarks, Explore and Lists one click away](assets/readme/new-tab.webp)

### Every theme a different Twitter

Fourteen built-in themes, and not just colours: shapes, type, icons and layout. Windows 98 is a real
Windows 98. Contrast is enforced for every theme, built in or imported.

![The same window in four built-in themes: Terminal, Paper, Frutiger Aero and Nord](assets/readme/themes.webp)

### Links come alive in chats

X's web chat shows a link as a bare card with the site's name. Chat+ shows the page's title, text and
picture, and plays YouTube, Vimeo and SoundCloud right in the chat. Only the link is sent to its site,
without cookies. Chat+ also keeps the messages you star: open one from your starred list and you are
back at it, with X's own Reply ready. It never reads, types or sends anything on its own.

![A YouTube link in a chat between our own accounts, shown by Chat+ as a card with the thumbnail, title and channel](assets/readme/chat-plus.webp)

### X in a language X doesn't have

String packs re-word X with data, never code: a language X does not offer, a better translation,
or your own wording. Here, Esperanto: Afiŝoj, Respondoj, Sekvataj.

![The Esperanto string pack turned on: a profile reads Afiŝoj, Respondoj, Sekvataj, next to the Languages settings](assets/readme/string-pack.webp)

### A plugin for every part of X

Eight area plugins (Compose+, Reader+, Profile+, Chat+, Media+, Search+, Notifications+,
Navigation+), each a switch with its features inside. The wB button in every pane opens the rest:
tabs and splits, language, theme, mode, zoom, Store, Workspaces, Drafts and find in page.

![Settings, Plugins: the eight area plugins with their switches, next to an X pane](assets/readme/plugins.webp)

### Signed, and nothing installs behind your back

Themes, plugins, string packs and icon packs come from the signed Store, a `waybetter://` link or a
file dropped on the window. Every install shows a screen first: name, source, size, SHA-256,
permissions and the code. Nothing installs until you confirm.

![The Store: themes, plugins, icon and language packs from a signed, verified catalog](assets/readme/store.webp)

## Install

| | Download | First launch |
| --- | --- | --- |
| **Windows** | [Installer (.exe)](https://waybetter.fyi/v1/download/windows/latest) | Installs per user, no admin. Not code-signed yet: SmartScreen says "unknown publisher"; choose More info, Run anyway. |
| **macOS** (universal) | [App (.app.tar.gz)](https://waybetter.fyi/v1/download/darwin/latest) | Unpack and move to Applications. Not notarized yet: the first time, allow it in System Settings, Privacy & Security, Open Anyway. |
| **Linux** x86-64 | [AppImage](https://waybetter.fyi/v1/download/linux/latest) | `chmod +x` the file and run it. |

All downloads, release notes and the Store are on [waybetter.fyi/x](https://waybetter.fyi/x/). The
app updates itself with signed updates. Sign in to X in the app as usual.

## Features

| Area | What you get |
| --- | --- |
| **Window** | Tabs and split panes with an address bar each, drag links to split, pinned tabs, restore on launch, per-tab zoom, find in page, command palette (Ctrl+K), link routing (beside, new tab, browser) |
| **Accounts** | Every account in its own profile, signed in at once; "open as" any account; per-account and per-pane themes |
| **Deck** | Columns of X (Ctrl+Shift+D): Home, Following, Notifications, Mentions, Search, List, Profile, Bookmarks, each in the account you pick, with unread counts and filters. Every column is the real x.com. See [docs/POWER-USER.md](docs/POWER-USER.md) |
| **Fixes** | The like, repost, bookmark and follow race; upload retry; timeline fixes. No plugin switch turns them off |
| **Area plugins** | Compose+, Reader+, Profile+, Chat+, Media+, Search+, Notifications+, Navigation+: one card each, a switch per feature. Modes Basic, Advanced and Power User are starting points, never locks. See [docs/AREA-PLUGINS.md](docs/AREA-PLUGINS.md) |
| **Drafts** | What you type in X's composers is kept locally with every revision, to restore, compare or export |
| **Look** | 14 themes, a Theme Builder with a doctor report and Google Fonts per role, icon packs (Line, Classic, Aero, Pixel, Windows 98, Windows XP), custom CSS. A theme is one JSON file: [docs/THEMES.md](docs/THEMES.md) |
| **Languages** | The app in 51 languages (17 supported, the rest community drafts); string packs for X itself, including the built-in "Tweet" wording |
| **Store** | One signed catalog of themes, plugins, string packs and icon packs, in the app and at [waybetter.fyi/store](https://waybetter.fyi/store/). Open With for `.plugin.js`, `.strings.json`, `.icons.json` and theme files |
| **Your setup** | Workspaces (tabs, splits, decks, accounts, pane themes) in one click; backup to one `.waybetter` file; encrypted sync through a folder you already sync; share your look as a link |
| **Make** | `*.plugin.js` plugins with declared `@permissions`, runnable examples and the UI kit in the app, developer mode with live reload. See [docs/PLUGINS.md](docs/PLUGINS.md) |
| **Safe mode** | Start with `--safe-mode` or hold Shift: X with none of the above, for that run only |

## Privacy

- The app never posts, likes, follows, unfollows or deletes anything by itself, never collects
  direct messages and never reads your credentials. It works with the data X already loads for the
  page and makes no requests of its own to X.
- Settings, drafts and plugins stay on your machine. Backups and sync snapshots never contain
  cookies, WebView profiles, tokens or keys.
- The app contacts only the update server (signed updates), the Store (signed catalog and the files
  you choose; only waybetter.fyi, cdn1.crt.fyi and git.crt.fyi) and, when you pick a Google Font,
  Google's font hosts. There is no analytics of any kind.
- X can change its website at any time; a feature that depends on a part X changed pauses itself
  and says so. Using a modified client is your decision; read X's terms.

## Build it from source

Requirements: Bun 1.4.2+, Node 24+, Rust stable and the
[Tauri prerequisites](https://v2.tauri.app/start/prerequisites/).

```sh
git clone --recurse-submodules https://git.crt.fyi/CRT/waybetter-for-x.git
cd waybetter-for-x
bun install --frozen-lockfile
bun run dev              # the desktop app with live reload of the page runtime
bun run build            # contracts, api, desktop (type check, bundles, vite)
bun run test             # contracts, api, web, desktop
bun run test:rust        # cargo tests, headless
bun run desktop:build    # an unsigned native build (no installer)
```

| Path | What lives there |
| --- | --- |
| `apps/desktop/src/shell` | The window's own UI: X's pages, address chips, palette items, decks, the compose dock |
| `apps/desktop/src/inject` | The runtime injected into X tabs: features, themes, `window.wayBetter` plugin API |
| `apps/desktop/src/areas` | The eight area plugins and the one feature table they share |
| `apps/desktop/src/fixes` | Fixes for X's own bugs (mutation gate, upload retry, timeline) |
| `apps/desktop/src-tauri` | Rust: X's site adapter, the drafts vault, IPC policy and the app's commands |
| `apps/web` | The website (waybetter.fyi) and the Store's pages |
| `apps/api` | The update and download API |
| `store/` | The Store's items for X (themes, plugins, packs) |
| `waybetter/` | The framework (git submodule; also on npm as [`waybetter`](https://www.npmjs.com/package/waybetter)) |

Everything generic (window, tabs, profiles, themes, the Store and install rules, backup, sync,
updates, the panel) lives in the framework; this repository configures it for X.

## Contributing

Bug reports, fixes, themes, plugins and translations are welcome: [CONTRIBUTING.md](CONTRIBUTING.md).
To put a theme or plugin in the Store, add one folder under `store/` in a pull request
([store/README.md](store/README.md)). Translations: [docs/TRANSLATING.md](docs/TRANSLATING.md).
Security issues: [SECURITY.md](SECURITY.md). Third-party licences:
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## License

GPL-3.0-or-later. Made by [@CRTkafa](https://x.com/CRTkafa).