xBlockOrigin is a browser extension that automatically mutes X.com users from specified countries using X’s GraphQL APIs, persistent caching, and local storage.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/chefnaphtha/xBlockOrigin/llms.txt
Use this file to discover all available pages before exploring further.
Extension components
The extension consists of four main architectural components:Content scripts
Content scripts run directly on X.com pages and handle DOM scanning and user detection:- orchestrator.ts - Main processing logic that coordinates all scanning operations
- timelineScanner.ts - Scans the home timeline for user posts
- searchScanner.ts - Scans search results pages
- statusScanner.ts - Scans post detail pages with replies
- replyScanner.ts - Scans notifications and replies
- profileScanner.ts - Scans user profile pages
- postHider.ts - Applies visual overlay to hide posts from blacklisted users
- flagInjector.ts - Injects country flags next to usernames (optional)
Content scripts have access to the page’s DOM but run in an isolated JavaScript context separate from the page’s scripts.
Background worker
The background service worker (Manifest V3) or persistent background page (Manifest V2) handles:- Extension lifecycle management
- Cross-tab communication
- Storage access coordination
Popup UI
Preact-based popup interface providing:- Country blacklist management
- Whitelist management (WhitelistManager.tsx)
- Settings configuration (Settings.tsx)
- Muted users database viewer
- CSV export functionality
- Statistics dashboard
Utilities layer
Shared utilities used across components:- cache.ts - Persistent TTL-based caching (24h for countries, 5m for following)
- rateLimit.ts - API request queue with sequential processing
- csvExporter.ts - Export muted users to CSV format
Architecture flow
The orchestrator coordinates the entire user processing pipeline:Processing steps
- Page scanning - Scanner detects username and tweet element on current page
- In-flight check - Prevents duplicate processing of same user
- User data fetch - Gets
userIdandfollowingstatus (cached 24h / 5m) - Whitelist check - Skips if user is whitelisted
- Following check - Optionally skips users you follow (default)
- Country detection - Fetches country from X.com API (cached 24h)
- Blacklist check - Checks if country is in blacklist
- Post hiding - Immediately applies 50% opacity + 8px blur overlay
- API mute - Calls X.com’s mute API (only for new users)
- Database save - Stores muted user with timestamp
The orchestrator uses an in-flight tracking set to prevent race conditions when the same user appears multiple times on the page.
Page detection
The orchestrator detects which X.com page is currently active and starts appropriate scanners:Home timeline (
/home or /) - scans timeline postsSearch results (
/search) - scans search result tweetsNotifications page (
/notifications) - scans replies and mentionsPost detail page (
/{username}/status/{id}) - scans main post and repliesUser profile pages (
/{username}) - scans user’s tweetsNavigation handling
The extension monitors for navigation events using:- popstate event - Detects browser back/forward navigation
- URL polling - Detects SPA navigation (100ms interval)
- Scanner cleanup - Clears old scanners and API queue on navigation
Multi-browser support
xBlockOrigin supports both Chrome/Edge and Firefox with different manifest versions:| Browser | Manifest | Background Type |
|---|---|---|
| Chrome/Edge | V3 | Service worker |
| Firefox | V2 | Persistent background page |
chrome.* APIs which are supported by both browsers through WebExtensions API compatibility.