Introduction to Messenger Unleashed

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• CLAUDE.md
• AGENTS.md
• src/main/index.ts
• src/preload/index.ts
• src/preload/settings-modal.ts
• src/main/chat-head.ts

Messenger Unleashed is an Electron-based desktop application designed as an enhanced wrapper for the Facebook Messenger web service (messenger.com). Its primary purpose is to provide a native-feeling desktop experience while introducing advanced features such as privacy controls, custom themes, and power-user tools that are absent from the standard web or official desktop versions.

Sources: CLAUDE.md:1-8, README.md:1-5

The application architecture relies on a single main process that handles window management, system tray integration, and persistent settings, while using preload scripts to bridge Electron APIs with the Messenger web environment. This allows for seamless CSS injection and JavaScript execution to modify behavior without altering the underlying web application.

Sources: CLAUDE.md:14-16, AGENTS.md:5-10

Core Architecture

The system is built on Electron and follows a centralized process model where src/main/index.ts serves as the entry point for all application logic.

Process Organization

• Main Process (src/main/index.ts): Manages the application lifecycle, creates BrowserWindow instances, handles global shortcuts, and persists user configuration using electron-store.
• Preload Scripts (src/preload/index.ts, src/preload/settings-modal.ts): Acts as a security bridge, exposing specific ipcRenderer functionality to the renderer via contextBridge.
• Theme System (themes.css): Contains static CSS definitions for various visual modes like "OLED Dark" and "Compact," which are injected at runtime.

Sources: CLAUDE.md:14-25, AGENTS.md:5-15, package.json:5-7

Application Lifecycle Flow

The following diagram illustrates how the application initializes and sets up its primary components upon startup.

Key Feature Modules

Privacy and Stealth Tools

Messenger Unleashed provides a suite of tools to manage user presence and read status. These are implemented by intercepting network requests and overriding browser APIs.

• Read Receipt Blocking: Intercepts outgoing AJAX and GraphQL requests matching patterns like mark_seen.php or MarkThreadRead.
• Typing Indicator Suppression: Blocks requests to typ.php and filters WebSocket frames containing is_typing payloads.
• Active Status Blocking: Overrides document.hidden and document.visibilityState to always report "hidden," and filters presence-related WebSocket updates.

Sources: src/main/index.ts:200-240, src/preload/index.ts:200-230, CLAUDE.md:46-51

Power User Functionality

Feature	Description	Implementation Detail
Quick Replies	Templates sent via Cmd+Shift+[Key]	DOM manipulation via InputEvent
Picture-in-Picture	Floating mini-chat window	Frameless BrowserWindow with ESC handler
Quiet Hours	Scheduled Do Not Disturb	Minute-based polling in main process
Chat Heads	Floating avatar for active chat	70x70 transparent BrowserWindow
Clipboard Sanitizer	Strips tracking metadata from URLs	paste event listener in preload

Sources: src/main/index.ts:470-490, src/main/index.ts:1170-1200, src/main/chat-head.ts:50-80, src/preload/index.ts:380-410

Interaction Sequence: Quick Replies

This sequence demonstrates how a user-triggered shortcut results in a message being sent through the Messenger interface.

Technical Implementation Details

CSS and JavaScript Injection

The application uses webContents.insertCSS for visual modifications and webContents.executeJavaScript for behavioral changes. Features are often toggled by adding or removing CSS via a specific cssKey.

// Example: Focus Mode Implementation
function toggleFocusMode() {
  const newValue = !store.get("focusMode");
  if (newValue) {
    mainWindow.webContents.insertCSS(`
      div[aria-label="Chats"], div[role="navigation"] { display: none !important; }
      div[role="main"] { width: 100% !important; }
    `, { cssKey: "focus-mode" });
  } else {
    mainWindow.webContents.reloadIgnoringCache();
  }
}

Sources: src/main/index.ts:446-465, CLAUDE.md:76-85

WebSocket Interception

To control granular behavior like typing indicators in real-time, the preload script wraps the native window.WebSocket constructor. It decodes outgoing frames and prevents transmission if they match forbidden patterns.

Sources: src/preload/index.ts:65-110, src/main/index.ts:280-320

Configuration and Persistence

User preferences are persisted across sessions using electron-store, stored in a local config.json file.

Configuration Key	Type	Default	Description
theme	String	default	Current UI theme ID
blockReadReceipts	Boolean	false	Stealth mode for reading messages
alwaysOnTop	Boolean	false	Keeps window above all others
quickReplies	Array	[]	List of {key, text} objects
windowBounds	Object	{width: 1000, height: 800}	Last known window dimensions

Sources: src/main/index.ts:1220-1250, CLAUDE.md:21-25, src/preload/settings-modal.ts:180-210

Conclusion

Messenger Unleashed serves as a high-performance desktop extension for Messenger, prioritizing user privacy and customization. By leveraging Electron's ability to intercede between the web content and the system, it provides a feature-rich environment that remains compatible with the standard Messenger ecosystem.

Sources: README.md:1-10, CLAUDE.md:90-95