BetterCurseForge/docs/guide/installation.md

Installation & Usage

How to install, check, and remove BetterCurseForge, using either the desktop app or the command line.

---

Prerequisites

You need:

• Windows 10 or Windows 11 (64-bit)
• CurseForge Launcher installed (standalone or Overwolf edition)
• CurseForge closed when you run the patcher

::: tip BACKUPS Before it changes anything, BetterCurseForge saves untouched copies of the original files at resources/app.asar.vanilla and CurseForge.exe.vanilla. You can go back to stock CurseForge whenever you want, with one click. :::

---

Option 1: Desktop GUI (recommended)

BetterCurseForge is a single executable with a dark-themed GUI.

Step 1: Download BetterCurseForge.exe

Grab the latest build from the releases page:

• Download BetterCurseForge.exe

Put it anywhere you like (Downloads, a tools folder, the desktop).

Step 2: Open BetterCurseForge

Double-click BetterCurseForge.exe to open it.

{width=64 style="display:block;margin:1rem auto;"}

On startup it:

• Finds your CurseForge install folder through the Windows Registry.
• Checks whether CurseForge is vanilla or patched.
• Shows the installed CurseForge version and install directory.

Step 3: Click "Patch CurseForge"

1. Click the Patch CurseForge button.
2. The patcher closes any running CurseForge processes, backs up the vanilla files, applies the patch (ad blocking, theme engine, skin unlocks, plugin loader), updates the integrity signature in the executable, and repacks the app.
3. The log panel shows progress as it goes:

   [+] Found CurseForge at: C:\Users\Username\AppData\Local\Programs\CurseForge Windows
   [+] Unlocked native premium themes (2 route checks)
   [+] Unlocked premium theme state validation
   [+] Unlocked subscription plan status for themes (4 checks)
   [+] Injected zero-ad and theme CSS rules into desktop.css
   [+] Bundled BetterCurseForge runtime into asar
   [+] Injected main-process hooks into background.js
   [+] Injected renderer script into desktop.html
   [+] Injected renderer loader into preload.js
   [+] Updated CurseForge.exe integrity signature
   [+] Auto-repatch watcher active and persistent across updates.
   [*] CurseForge successfully patched! Ads removed, themes & plugins enabled.
   

4. Click Launch CurseForge or start it from your usual shortcut. That's it.

---

Option 2: Command line

If you want to script it or run it without the GUI, BetterCurseForge.exe has a CLI.

Patching

Open PowerShell or Command Prompt in the folder with BetterCurseForge.exe:

::: code-group

.\BetterCurseForge.exe patch

BetterCurseForge.exe patch

:::

Checking status

See whether CurseForge is patched:

.\BetterCurseForge.exe status

Output:

CurseForge Status: PATCHED (BetterCurseForge v1.0.0)
Path: C:\Users\Username\AppData\Local\Programs\CurseForge Windows
ASAR Hash: Verified

Unpatching

Go back to stock CurseForge:

.\BetterCurseForge.exe unpatch

This restores resources/app.asar from the vanilla backup and re-verifies the original executable signatures.

---

Auto-repatch after CurseForge updates

When CurseForge updates itself, it overwrites app.asar with a stock copy and restarts.

BetterCurseForge handles this without the unpatched launcher ever showing up on screen.

Managing it in the GUI

• Toggle the Auto-Repatch on Update button in the app. It turns green when it's on.

Managing it from the CLI

# Run the background watcher daemon directly:
.\BetterCurseForge.exe watch

# Trigger the smooth splash updater GUI manually:
.\BetterCurseForge.exe --repatch-splash

# BetterCurseForge also manages watcher persistence automatically on patch/unpatch:
.\BetterCurseForge.exe patch    # Applies patch and activates watcher autostart
.\BetterCurseForge.exe unpatch  # Restores vanilla client and stops watcher

How it works

1. Background watcher: Runs in the background on Windows directory change notifications and periodic heartbeat checks, so CPU use is negligible.
2. Killing the stock launcher: Once it sees an update or an unpatched install, the watcher polls every 150 ms with Win32 process enumeration. If the installer starts CurseForge.exe, the watcher kills it within 50 ms, before a window can appear.
3. Splash window: A dark #121214 card shows the app icon, a purple AUTO-UPDATE badge, a progress bar, and status messages while it extracts, unlocks themes, blocks ads and repacks.
4. Offline repatch: Extracting and repacking the ASAR takes 2–3 seconds and needs no internet. It uses the Node v24 runtime bundled with CurseForge (ELECTRON_RUN_AS_NODE=1) and writes the new OWEASARSIG hash into CurseForge.exe.
5. Relaunch: The patched CurseForge opens and the splash window closes.

---

Under the hood

Recent CurseForge versions verify the integrity of app.asar from inside CurseForge.exe. This is the patch flow:

flowchart TD
    A["BetterCurseForge.exe"] --> B["Locate CurseForge Windows Installation"]
    B --> C["Extract app.asar & Create Vanilla Backup"]
    C --> D["Unlock Native Premium Themes & Validate Subscription State"]
    D --> E["Inject Zero-Ad & Theme CSS into desktop.css"]
    E --> F["Bundle BetterCurseForge Runtime (Main, Preload, Renderer)"]
    F --> G["Repack app.asar & Calculate SHA256 Header Hash"]
    G --> H["Update CurseForge.exe OWEASARSIG Integrity Signature"]
    H --> I["Launch Modded CurseForge with Full Permissions"]

1. Ad blocking: Ad requests are blocked at the Electron session level (session.webRequest), and CSS collapses the ad frames to 0px. The elements stay in the DOM, so React Fiber's reconciliation isn't affected.
2. Skin unlock: AST and regex matching, written to tolerate version changes, unlocks the official CurseForge skins (Pixelforge, Lifeforge, Fantasyforge, Halloween, etc.) in Settings -> Themes.
3. ASAR signature update: It computes the SHA256 hash of the modified ASAR header and writes it into CurseForge.exe, so Electron starts without integrity errors.

---

Troubleshooting

::: details How do I tell it's working?

1. Open CurseForge.
2. There should be no banner ads or video sponsor frames.
3. Go to Settings -> Themes. You should see a Client Themes section with Purple Night in it, and the Premium skins (Pixelforge, Lifeforge, etc.) unlocked.
4. Press Ctrl + Shift + I to open DevTools. The console should print:

   [BetterCF] Initializing renderer runtime...
   [BetterCF] Theme manager ready (1 theme(s) found). Active: purple-night.css
   [BetterCF] ✓ BetterCurseForge loaded successfully!
   

:::

::: details Antivirus flags the exe Some antivirus tools flag BetterCurseForge.exe as a false positive. It looks at running processes (CurseForge.exe), reads the Windows Registry to find the install path, and rewrites hashes in an executable, which is the kind of thing heuristic scanners react to. The project is open source: the Python code is in patcher/, and you can read it and build the exe yourself. :::

::: details Permission denied / EPERM error If CurseForge is installed under C:\Program Files, the patcher needs Administrator permissions to change files. Right-click BetterCurseForge.exe and choose Run as Administrator. :::