Blockingmachine Desktop

Modern, lightweight ad-blocking filter management tool for your desktop

---

Related Projects

• Blockingmachine Core
• Blockingmachine CLI
• Blockingmachine Database

---

Features

🚀 Advanced Filter Management

• Multiple Filter Sources: Import and manage filter lists from various sources
• Custom Rules: Add your own custom blocking rules alongside existing lists
• Smart Deduplication: Automatically removes duplicate rules to optimize performance
• Rule Statistics: View detailed information about processed rules

💡 User-Friendly Interface

• Light & Dark Mode: Adapts to your system theme or choose your preference
• Modern UI: Clean, intuitive interface with responsive design
• Interactive Dashboard: Visualize your filter statistics
• Progress Tracking: Real-time progress indicators during processing

🔄 Export Flexibility

• Multiple Application Support: Export to various formats including:
  • AdGuard Home
  • AdBlock Plus
  • uBlock Origin
  • Hosts File
  • dnsmasq
  • Unbound
  • Domain List
  • Plain Text

⚙️ Seamless Experience

• Automatic Updates: Stay current with the latest app improvements
• Cross-Platform: Works on Windows (Coming soon), macOS (Beta), and Linux (Linux support coming soon)
• Persistent Settings: Your configuration is saved between sessions
• Fast Processing: Efficient handling of even large filter lists
• User Feedback: We welcome your feedback to improve the app
• Community Driven: Open-source project with contributions from the community
• Privacy First: No data collection, your filter lists stay local
  • While this is a local application, we do not collect any data or telemetry. Your filter lists and rules are processed entirely on your machine.
  • We may change this in the future to allow for cloud processing and data sharing, but this will be an opt-in feature and will be clearly communicated.
  • We are committed to transparency regarding any future changes to data handling practices.

Installation

macOS (Beta)

1. Download the latest .dmg file from Releases
2. Open the .dmg file and drag Blockingmachine to your Applications folder
3. Open Blockingmachine from your Applications folder
4. The app should be properly signed and notarized. If you encounter a security warning, open Privacy & Security settings, scroll to the bottom, and allow the app to run

Windows (Coming Soon)

1. Download the latest .exe installer from Releases
2. Run the installer and follow the prompts
3. Launch Blockingmachine from the Start menu
4. Note: Windows support is currently in beta. Please see the Windows Support section for more details.
5. Known Limitations: The Windows version may require additional permissions for filter list generation and update functionality.
6. Reporting Windows Issues: If you encounter issues with the Windows version, please check our GitHub Issues to see if it's already reported.

Linux (Coming Soon)

1. Download the .AppImage or .deb package from Releases
2. Make the AppImage executable: chmod +x Blockingmachine*.AppImage
3. Run the AppImage or install the .deb package
4. Note: Linux support is coming soon. Please check back for updates.

Windows Support (Coming Soon)

The Windows version of Blockingmachine is currently in beta testing. While we've implemented all the necessary components for Windows support, it hasn't been extensively tested on all Windows configurations.

Known Limitations

• The Windows version may require additional permissions for filter list generation and update functionality
• Some visual elements may appear differently compared to the macOS version
• The app has been tested primarily on Windows 10/11, older versions may have compatibility issues

Windows-Specific Features

• Installation includes automatic setup of application folders
• Native Windows notifications for update alerts
• Option to run at startup (configurable in Settings)
• Context menu integration for .blocklist files

Reporting Windows Issues

If you encounter issues with the Windows version:

1. Please check our GitHub Issues to see if it's already reported
2. If not, submit a new issue with:
   • Your Windows version
   • Steps to reproduce the problem
   • Any error messages you receive
   • Screenshots if applicable

We're actively working to improve the Windows experience and appreciate your feedback during this beta phase.

Quick Start

1. Add Filter Sources

   • Navigate to the Sources tab
   • Add popular filter lists or custom sources
   • Enable the sources you want to use

2. Add Custom Rules (Optional)

   • Navigate to the Custom Rules tab
   • Add any specific rules you need

3. Process Rules

   • Go to the Process tab
   • Click "Generate Filter Lists"
   • Wait for processing to complete

4. Use Your Generated List

   • Find your exported file in the configured save location
   • Import it into your ad-blocker or DNS blocker of choice

Development Timeline

Current Release (v1.0.0-beta.3)

• 🚀 Core functionality implementation
• 💻 macOS support (beta - stable)
• 🔄 Automatic updates (beta)
• 🌓 Light and dark mode
• 📊 Basic statistics dashboard
• 🗄️ Multiple export formats
• 🔍 Rule filtering capabilities
• 🐞 Initial bug fixes

Upcoming Features (v1.0.0)

• 📱 Enhanced UI responsiveness
• 🖥️ Windows support
• 🐧 Linux support
• ⚡ Performance optimizations for large lists
• 💾 Better offline capabilities
• 📝 Enhanced logging and diagnostics
• 🔔 Customizable notifications
• 🔄 Background list updates

Future Roadmap (v2.0+)

• 🌐 Built-in network monitoring
• ☁️ Optional cloud synchronization
• 📊 Advanced analytics dashboard
• 🧩 Extension/plugin system
• 🛡️ Enhanced security features
• 🔧 Rule editor with syntax highlighting
• 🌍 Internationalization support
• 📂 Profile management for different devices/networks

Version History

1.0.0-beta.3 (Latest)

• Fixed critical stability issues
• Enhanced dark mode implementation
• Improved memory usage for large filter lists
• Documentation improvements
• Updated README for clarity and consistency
• ** Had to delay Windows support due to critical issues with the installer. I am working on a fix and will release an update soon. **

1.0.0-beta.2

• 🎉 Initial public beta release
• Performance optimizations
• Improved UI responsiveness
• Added export to additional formats
• Fixed file handling issues
• Enhanced status reporting
• Added auto-update functionality
• Added basic dashboard statistics

1.0.0-beta.1

• Initial macOS-only release
• Basic UI implementation
• Core filtering functionality
• Settings persistence
• Essential export options

Advanced Usage

Managing Filter Sources

// Example filter source structure
{
  "name": "EasyList",
  "url": "https://easylist.to/easylist/easylist.txt",
  "enabled": true
}

Custom Rules Syntax

Blockingmachine supports standard AdGuard/AdBlock Plus syntax:

  ! Comment line (ignored)
  ||example.com^
  @@||whitelisted-domain.com^
  domain.com/ads/*

Export Format Details

Format	Description	Best For
adguard	AdGuard Home compatible	AdGuard Home, AdGuard DNS
abp	AdBlock Plus compatible	Browser extensions
hosts	Hosts file format	System-level blocking
dnsmasq	dnsmasq configuration	Routers, Pi-hole
unbound	Unbound DNS configuration	Custom DNS servers
domains	Simple domain list	DNS blocklists
plain	Raw text list	Custom implementations

Troubleshooting

Common Issues

1. Application doesn't start

   • Check for error logs in the console
   • Verify your system meets the minimum requirements
   • Try reinstalling the application

2. Filter processing fails

   • Check your internet connection
   • Verify that filter source URLs are valid and accessible
   • Try with fewer sources if processing large lists

3. Export file not generated

   • Ensure you have write permissions to the save location
   • Check for error messages in the application
   • Try choosing a different save location

Debug Mode

Run Blockingmachine in debug mode to view detailed logs:

  # macOS/Linux
  DEBUG=blockingmachine:* /Applications/Blockingmachine.app/Contents/MacOS/Blockingmachine

  # Windows
  set DEBUG=blockingmachine:* & "C:\Program Files\Blockingmachine\Blockingmachine.exe"

Building From Source

Prerequisites

• Node.js 18.x or later
• npm or yarn
• Git

Setup

# Clone the repository
git clone https://github.com/greigh/Blockingmachine.git

# Navigate to the electron app directory
cd Blockingmachine/packages/electron-app

# Install dependencies
npm install

# Start the development server
npm start

# Build the application
npm run make

## Build Options

``` bash
# Build for macOS
npm run make -- --platform=darwin

# Build for Windows
npm run make -- --platform=win32

# Build for Linux
npm run make -- --platform=linux

Contributing

We welcome contributions to Blockingmachine Desktop! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Commit your changes: git commit -m 'Add some feature'
4. Push to the branch: git push origin feature/your-feature-name
5. Submit a pull request

Please read our Contributing Guide for more details.

Code Style

We use ESLint and Prettier to maintain code quality. Before submitting a pull request:

# Run linter
  npm run lint

  # Fix linting issues automatically
  npm run lint:fix

Technology Stack

• Electron: Cross-platform desktop application framework
• React: UI library for building interactive interfaces
• TypeScript: Type-safe JavaScript
• Recharts: Responsive charting library
• Electron Store: Persistent settings storage
• @blockingmachine/core: Core rule processing functionality

License

This project is licensed under the BSD-3-Clause License. Read the LICENSE file for details.

Made with ❤️ by Daniel Hipskind