NeuroForge

NeuroForge is a desktop focus application for macOS and Windows. It runs timed focus sessions, blocks distracting websites and desktop apps, supports blacklist/whitelist modes, and adds friction before a user can stop an active session.

Current Builds

Release binaries are kept in the repository root so visitors can download them immediately:

• macOS Apple Silicon: NeuroForge-arm64.dmg
• Windows installer: NeuroForgeSetup.exe

Local intermediate build outputs are written under build/ and are ignored by git except for Wails source assets such as build/appicon.png and build/darwin/Info.plist.

Features

• Timed and locked focus sessions
• Adjustable session duration in 1 minute increments
• Website blacklist and whitelist modes
• Application blacklist and whitelist modes
• Installed app picker on macOS and Windows
• Multiple schedules with one active schedule or all schedules paused
• Typing challenge before stopping protected sessions
• macOS close-to-background behavior during protected work
• Local SQLite persistence
• Local analytics and event export

Blocking Model

NeuroForge uses OS-level mechanisms. It does not use a browser extension.

Website blocking:

• macOS: /etc/hosts fallback plus PF packet filter rules for resolved remote IPs; while a session is active, NeuroForge refreshes the PF IP table to catch CDN/IP changes
• Windows: hosts fallback plus Windows Defender Firewall outbound remote IP rules
• Domain rules are normalized from URLs, so https://www.youtube.com/watch... becomes youtube.com
• Known high-traffic services are expanded to related API/CDN domains where practical
• Blocked websites may appear in the browser as a network failure, for example "You are not connected to the internet", "This site can't be reached", or a timeout. This is expected: NeuroForge blocks the connection at the OS/network layer instead of showing an in-page block screen.

Application blocking:

• macOS: blocked apps may launch briefly, then NeuroForge terminates the process
• Windows: blocked executable names are terminated through system process control
• The UI warns users about this behavior

Important limitation: without a privileged Network Extension, browser extension, or kernel-level driver, no consumer desktop app can perfectly block every modern web path in every browser/network configuration. NeuroForge’s current production path is hosts + OS firewall/PF enforcement.

Requirements

Development:

• Go 1.23+
• Node.js and npm
• macOS for DMG builds
• NSIS (makensis) for Windows installer builds

Runtime:

• macOS may ask for administrator approval once when a protected session starts and website blocking rules are applied. Adding/removing websites in the UI should not request administrator approval.
• Windows installer requests administrator privileges and installs under Program Files

Development

Install frontend dependencies:

cd frontend
npm ci

Build frontend assets:

cd frontend
npm run build:desktop

Run Go tests:

go test ./...

Real system-level integration tests are guarded and must be run intentionally:

NEUROFORGE_REAL_WEB_BLOCK_TEST=1 go test ./internal/core -run TestRealMacWebBlockerBlocksExampleDotCom -count=1 -v
NEUROFORGE_REAL_APP_BLOCK_TEST=1 go test ./internal/core -run TestRealMacAppBlockerKillsCalculator -count=1 -v

These tests modify local OS state temporarily and clean up after themselves.

Packaging

macOS DMG:

deploy/macos/build-dmg.sh

Output:

build/macos/NeuroForge-arm64.dmg

For repository distribution, copy the final DMG to the root:

cp build/macos/NeuroForge-arm64.dmg ./NeuroForge-arm64.dmg

Windows installer:

deploy/windows/build-installer.sh

Output:

build/windows/NeuroForgeSetup.exe

For repository distribution, copy the installer to the root:

cp build/windows/NeuroForgeSetup.exe ./NeuroForgeSetup.exe

Distribute NeuroForgeSetup.exe, not the raw neuroforge.exe.

Repository Layout

.
├── build/
│   ├── appicon.png              # Wails source app icon, tracked
│   └── darwin/Info.plist        # Wails macOS template, tracked
├── deploy/
│   ├── macos/build-dmg.sh
│   └── windows/
│       ├── build-installer.sh
│       └── neuroforge.nsi
├── frontend/
│   ├── src/
│   ├── package.json
│   └── package-lock.json
├── internal/
│   ├── core/                    # sessions, rules, schedules, blockers, storage
│   └── ui/                      # Wails API bindings
├── main.go
├── wails.json
├── go.mod
└── go.sum

What To Commit

Commit:

• Source code under internal/, frontend/src/, deploy/
• go.mod, go.sum
• frontend/package.json, frontend/package-lock.json
• wails.json
• build/appicon.png
• build/darwin/Info.plist
• root release artifacts: NeuroForge-arm64.dmg, NeuroForgeSetup.exe
• Documentation and packaging scripts

Do not commit:

• frontend/node_modules/
• frontend/dist/ or frontend/dist-landing/
• frontend/wailsjs/ generated bindings
• build/bin/, build/macos/, build/windows/
• nested .dmg, .exe, .app, .icns build outputs
• deploy/windows/NeuroForgeSetup.exe

Root-level NeuroForge-arm64.dmg and NeuroForgeSetup.exe are intentionally committed for direct downloads.

Distribution Notes

The current macOS build is ad-hoc signed. For public distribution without Gatekeeper friction, sign with an Apple Developer ID certificate and notarize the app/DMG.

The Windows installer is unsigned unless signed externally. For public distribution, sign NeuroForgeSetup.exe with a code signing certificate.

License

MIT License. See LICENSE.