Skip to main content

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.

This guide will walk you through installing xBlockOrigin, configuring your first country blacklist, and seeing it work on X.com.
Before starting, make sure you’re logged into X.com. The extension requires an active X.com session to function.

​
Installation

First, install the extension for your browser. Follow the detailed instructions in our installation guide, or use the quick steps below:
1

Download the extension

Download the appropriate version from GitLab Releases:
  • Chrome/Edge: xblockorigin-chrome-rX.zip
  • Firefox: xblockorigin-firefox-rX.zip
2

Install in your browser

  1. Unzip to a permanent folder
  2. Go to chrome://extensions/
  3. Enable “Developer mode”
  4. Click “Load unpacked”
  5. Select the unzipped folder
3

Verify installation

Look for the xBlockOrigin icon in your browser’s extension toolbar

​
Configure your first country blacklist

Now let’s add a country to your blacklist:
1

Open the extension popup

Click the xBlockOrigin icon in your browser toolbar to open the popup interface
2

Add a country

In the “Country Blacklist” section:
  1. Enter a country name in the input field (e.g., “United States”, “Russia”, “Antarctica”)
  2. Click the “Add” button
Country names must match X.com’s country detection format. Use full country names like “United States” rather than abbreviations.
3

Verify the country was added

The country should now appear in your blacklist below the input fieldYou can add multiple countries by repeating the process
4

Configure settings (optional)

Click the “Settings” tab to customize behavior:
  • Show country flags: Display flags next to usernames (visual indicator)
  • Also mute users you are following: By default, users you follow are NOT muted. Enable this to mute everyone from blacklisted countries, even users you follow
Enabling “Also mute users you are following” will mute your followed users from blacklisted countries. Most users should keep this disabled.

​
See it in action

Now let’s browse X.com and watch xBlockOrigin automatically mute users:
1

Navigate to X.com

Open X.com in a new tab (make sure you’re logged in)
2

Browse your timeline

Scroll through your timeline, search results, or visit user profilesThe extension works on:
  • Timeline (home feed)
  • Search results
  • User profiles
  • Post detail pages with replies
  • Notifications
3

Watch posts get hidden

When xBlockOrigin detects a user from a blacklisted country:
  1. The post is immediately hidden with a 50% opacity overlay and 8px blur
  2. The overlay adapts to your X.com theme (light or dark mode)
  3. A toast notification appears: “Muted @username (Country)”
  4. The user is muted via X.com’s API
4

Interact with hidden posts (optional)

You have several options for interacting with hidden posts:Option 1: Unhide the post
  • Click “Unhide” on the overlay to reveal the post content
  • A notice appears: “Post unhidden, but user is still muted”
  • The user remains muted on X.com
Option 2: Unmute and whitelist
  • Click “Unmute and whitelist” on the overlay
  • The user is unmuted via X.com’s API
  • The user is added to your whitelist (never muted again)
  • All of their posts are unhidden immediately

​
Managing whitelisted users

Whitelist users you never want to mute, regardless of their country:
1

Open the extension popup

Click the xBlockOrigin icon in your browser’s extensions toolbar to open the popup
2

Add a user to whitelist

In the “Whitelisted Users” section:
  1. Enter a username (without the @ symbol)
  2. Click “Add”
Whitelisted users are never muted, even if they’re from a blacklisted country
3

Remove from whitelist

Click the ”×” button next to any username to remove them from the whitelist

​
Viewing muted users

Track all users that have been automatically muted:
1

Open the extension popup

Click the xBlockOrigin icon to see the muted users list
2

Browse muted users

The popup displays:
  • Total number of muted users
  • Statistics about top countries
  • Sortable list by username, country, or mute date
3

Export to CSV

Click “Export to CSV” to download a CSV file containing:
  • Username
  • User ID
  • Country
  • Timestamp when muted
Great for backing up your data or analyzing muting patterns

​
Understanding the cache

xBlockOrigin uses intelligent caching to minimize API requests:
  • User IDs: Cached for 24 hours
  • Countries: Cached for 24 hours
  • Following status: Cached for 5 minutes
  • In-flight requests: Prevents duplicate API calls for the same user
This means that if a user’s country changes (X updates this every 30 days), xBlockOrigin will pick up the change within 24 hours when the cache expires.

​
Privacy and security

xBlockOrigin is built with privacy in mind:

Local storage

All data (blacklist, whitelist, muted users) is stored locally on your device using Chrome’s secure storage APIs

No external servers

xBlockOrigin never sends data to external servers - it only communicates with X.com’s official API

Sync storage

Country blacklist and settings use chrome.storage.sync to sync across your devices (if you’re logged into Chrome/Firefox)

Open source

The entire codebase is open source and available for review on GitLab

​
Advanced features

​
Request queue optimization

xBlockOrigin processes API requests efficiently:
  • All requests are queued and processed sequentially (no concurrent requests)
  • Combined UserByScreenName call fetches both user ID and following status in a single request
  • In-flight request tracking prevents duplicate API calls

​
Multi-page support

The extension uses specialized scanners for different X.com pages:
  • Timeline scanner: Monitors your home feed
  • Search scanner: Processes search results
  • Profile scanner: Scans user profile pages
  • Status scanner: Handles post detail pages
  • Reply scanner: Processes notifications and replies

​
Post hiding overlay

The overlay system preserves post functionality:
  • Original post remains in the DOM with all click handlers intact
  • Overlay uses 50% opacity background matching your theme
  • 8px blur effect for visual obscuration
  • Click “Unhide” to interact with the post without unmuting the user

​
Troubleshooting

​
Posts aren’t being hidden

1

Check you're logged in

xBlockOrigin requires an active X.com session. Log in to X.com and refresh the page.
2

Verify country is in blacklist

Open the extension popup and confirm the country is listed in your blacklist
3

Check following protection

If “Also mute users you are following” is disabled (default), users you follow won’t be muted
4

Clear cache

Countries are cached for 24 hours. If you just added a country, previously scanned users won’t be re-checked until cache expires

​
Extension stopped working

X.com’s API may change, requiring updates to query IDs. Check for extension updates on the GitLab Releases page.
  1. Check browser console for errors (F12 → Console)
  2. Verify extension is enabled in your browser’s extensions page
  3. Try disabling and re-enabling the extension
  4. Check for updated versions on GitLab

​
Country detection seems wrong

Country detection is based on X’s geolocation of the user’s IP address. According to X, this is updated every 30 days. If a user uses a VPN or travels, their detected country may not match their actual location.

​
Next steps

You’re now ready to use xBlockOrigin effectively! Here are some suggestions:
  • Add multiple countries to your blacklist for comprehensive filtering
  • Whitelist trusted users from blacklisted countries
  • Export your muted users list regularly for backup
  • Customize settings to match your preferences
  • Check the GitLab repository for updates and new features

Installation guide

Detailed installation instructions for all browsers

GitHub repository

View source code, report issues, and contribute

Build docs developers (and LLMs) love

Get started for freeTalk to us