goodx

A privacy-focused Twitter/X frontend written in Rust. Forked from teapot.

Features

• Privacy-focused: No third-party JavaScript, tracking, ads, or remote fonts
• RSS feeds: Subscribe to any user's tweets, replies, media, search
• FxEmbed-style Discord embeds:
  • Multiple images displayed in carousel on mobile
  • Videos play directly in the embed
  • Proper image dimensions for better layout
  • ActivityPub JSON endpoint for rich embeds
• Multi-user timelines: View tweets from multiple users at once
• Themes: 10+ built-in themes (goodx, Twitter, Dracula, Mastodon, etc.)
• Keyboard navigation: j/k, Enter, / search
• Infinite scroll: Optional JS-powered pagination
• Translation: Kagi Translate integration
• Media proxy: All media proxied through the server for privacy
• Articles: Full support for Twitter Articles (long-form notes)

Requirements

• Rust 1.96.1+
• Twitter/X session tokens for API access

Building

cargo build --release

Configuration

1. Copy the example config:

cp config/goodx.example.toml config/goodx.toml

2. Edit config/goodx.toml with your settings.

3. Create a sessions file with your Twitter/X credentials:

cp sessions.example.jsonl sessions.jsonl
# Edit sessions.jsonl with your auth_token and ct0 from browser cookies

Cookie sessions use auth_token and ct0. OAuth sessions use oauth_token and oauth_secret. See sessions.example.jsonl for the JSONL shape. Never commit a real session or generated goodx.toml.

Running

# Development
cargo run

# Production
./target/release/goodx

The server will start on http://localhost:8080 by default.

Configuration can be overridden via environment variables:

• GOODX_CONF_FILE (or legacy TEAPOT_CONF_FILE) — path to config file
• GOODX_SESSIONS_FILE (or legacy TEAPOT_SESSIONS_FILE) — path to sessions

Getting Twitter Sessions

To use the Twitter API, you need session tokens from a logged-in Twitter account:

1. Log into Twitter/X in your browser
2. Open Developer Tools (F12) → Application → Cookies
3. Copy the values of auth_token and ct0
4. Add them to sessions.jsonl

Project Structure

goodx/
├── src/
│   ├── main.rs          # Entry point
│   ├── config.rs        # Configuration
│   ├── error.rs         # Error types
│   ├── types/           # Data structures (User, Tweet, Timeline, etc.)
│   ├── api/             # Twitter API client, OAuth, parsing
│   ├── cache/           # In-process caching
│   ├── routes/          # HTTP route handlers
│   ├── views/           # Maud HTML templates
│   └── utils/           # Utilities (HMAC, formatters)
├── public/              # Static assets (CSS, JS, fonts)
├── config/              # Configuration files
└── Cargo.toml           # Dependencies

Routes

Path	Description
/	Home — search
/search	Search (tweets, users, media, videos)
/{username}	User timeline
/{username}/with_replies	User tweets & replies
/{username}/media	User media
/{username}/status/{id}	Tweet detail + replies
/{username}/status/{id}/retweets	Retweets list
/{username}/status/{id}/quotes	Quotes list
/{username}/status/{id}/history	Edit history
/{username}/lists/{slug}	List timeline
/{username}/article/{id}	Twitter Article (Notes)
/{username}/rss	RSS feed
/settings	User preferences
/about	About this instance
/embed/Tweet.html	Tweet embed HTML
/oembed	oEmbed JSON
/users/{username}/statuses/{id}	ActivityPub JSON
/api/v1/statuses/{id}	Mastodon API

Preferences

All preferences are stored in cookies (no account needed). Shareable preference URLs can be generated from the settings page. Query parameters can override any preference per-request (e.g. ?theme=twitter&hideReplies=on).

Themes

goodx ships with 10+ themes: goodx, goodx_light, black, dracula, mastodon, pleroma, twitter, twitter_dark, auto (system preference-based).

License

GNU Affero General Public License v3.0