Vitreous

A free, open-source, local-first focus blocker for Windows — wrapped in an Apple-style liquid-glass UI.

Block distracting websites and apps — on demand, on a timer, or on a schedule — then lock it down so you can't undo it in a weak moment. Runs entirely on your machine: no backend, no accounts, no telemetry.

⬇️ Download for Windows · 🌐 Website · 📦 Releases · 🐛 Report a bug

⬇️ Download & install

Grab the latest installer: Vitreous-Setup-0.1.0.exe (~92 MB, Windows 10/11 · x64).
Run it — it installs per-user (no admin needed to install) and launches automatically.
First run: the installer isn't code-signed yet, so Windows SmartScreen may show "Windows protected your PC". Click More info → Run anyway. (A free OV code-signing application to the SignPath Foundation has been submitted and is under review.)

The first time you start a block, Windows asks for admin once to install a tiny background helper — after that, blocking applies silently forever. See How blocking works.

Prefer a landing page? Everything's also at the download site.

✨ Features

🎯 Focus & blocking

🌐 Website blocking — block sites (YouTube, Reddit, …) at the OS level via the Windows hosts file. Each domain is expanded to its apex + www.
🧩 App blocking — force-close distracting apps/games (kill-on-sight while a session runs). Add apps by picking a running window, typing the exe name, or browsing for an .exe.
⏱️ Sessions — block for a set duration (e.g. 25 / 60 min) or until you stop.
📅 Scheduling — recurring windows (daily, specific weekdays, a single date, or a date range — including overnight) that block even when the app is closed.
🔒 Lockdown (mandatory) — every session is a locked session: a typed stop-gate (retype your reason + one-time passwords), a frozen add-only blocklist, and a self-healing watchdog that re-applies the locked state. Indefinite sessions keep their passwords viewable, so a lock is never an inescapable trap.

🧘 Stay on track

🖥️ Full-screen focus mode — an immersive, ambient liquid-glass timer for the duration of a session.
🎬 Session splashes — a "ready, steady, good luck" countdown on start and a motivating message on finish.
📊 Reflections — local activity history: focus time, block counts, a time-of-day heatmap, trends, and an optional daily focus goal.
💬 Quote of the day — a fresh motivational quote, with an offline fallback.
🔔 Notifications — start toasts and optional pre-start reminders with a customizable lead time.

🎨 Experience

🪟 Custom liquid-glass window with 7 themes — Cosmic Orange, Luxury Red, Lavender Haze, Obsidian Gold, Midnight Rose, Blush Mist, Jade Mist (plus system light/dark).
🧠 One UAC prompt, ever — manual Start/Stop enforce silently through a one-time elevated helper.
🔄 Auto-update — lock-safe background updates via electron-updater + GitHub Releases.
💾 100% local — settings, blocklists, and history live in local files and never leave your machine.

📸 Screenshots

Blocklist · Midnight Rose	Schedule · Lavender Haze

Reflections · Jade Mist	Settings · Obsidian Gold

The same app, seven themes — switch live on the website showcase.

🔧 How blocking works

Enabled website rules are written to a fenced # Vitreous region of the Windows hosts file (each domain → 0.0.0.0). Writing hosts needs admin, so:

A once-approved elevated Windows Scheduled Task is the single writer of the hosts file. It's installed the first time you start a block — one UAC prompt, ever.
After that, Start/Stop are silent: the app writes the desired state to settings.json and triggers the helper to apply it. If the helper is ever unavailable, it safely falls back to a direct elevated write, so blocking never silently fails.
The same elevated task reconciles state every minute, so scheduled blocks and lockdown self-heal even while the app is closed or after tampering.

Known limitation: system-clock rollback is not currently defended against.

🧩 Browser extension (optional companion)

A small Manifest V3 extension makes web blocking nicer: already-open distracting tabs flip to a tasteful block page instead of a connection error. It talks only to the local app over a loopback WebSocket (127.0.0.1) — the app is the source of truth, and the extension collects no data. See extension/ and extension/PUBLISHING.md.

🧱 Tech stack

Layer	Technology
App shell	Electron 31
Build tooling	Vite via `electron-vite`
UI	React 18 + plain CSS (custom properties — the "liquid glass" look)
Charts	Recharts (Reflections)
App ↔ extension	`ws` loopback WebSocket bridge
Enforcement	Node.js + Windows `hosts` file + an elevated Scheduled Task
Updates	electron-updater + GitHub Releases
Packaging	electron-builder (NSIS one-click installer)
Storage	Local `settings.json` + append-only `events.jsonl`
Browser helper	Manifest V3 extension (Chrome/Edge/Brave/Firefox)
CI/CD	GitHub Actions (installer build + Pages deploy)

🏗️ Architecture & engineering highlights

The hard parts — and the most interesting engineering:

Privileged OS enforcement without nagging the user. Modifying the Windows hosts file requires admin rights. A one-UAC-prompt-ever model uses a once-approved elevated Scheduled Task as the single writer, so all later Start/Stop actions apply silently, with a safe fallback to a direct elevated write.
Self-healing background reconciliation. An elevated task re-evaluates desired state every minute, so scheduled blocks and lockdown enforce themselves even when the app is closed, and survive tampering.
Tamper-resistant "lockdown" mode. Mandatory locked sessions with generated one-time passwords, a typed stop-gate, a frozen (add-only) blocklist, and a watchdog — designed so you can't trivially bypass your own commitment, while indefinite sessions never become a trap.
Local IPC bridge to a browser extension. A Manifest V3 companion talks to the desktop app over a loopback WebSocket (127.0.0.1); the app stays the single source of truth.
Pure, testable core logic. Desired-block computation is isolated as a pure function (src/main/enforce.js) and unit-tested, separated from the side-effecting OS layer.
Privacy as an architectural constraint. No server, no account, no telemetry — the only outbound call is an optional quotes API with an offline fallback.

👩‍💻 For developers

Prerequisites

Node.js 20+ and npm
Windows 10/11 to exercise the full enforcement layer (hosts writes, the scheduled-task helper, app killing). The app builds and the UI runs on any OS, but those OS-level flows are Windows-only.

Setup

git clone https://github.com/subhasisbiswal012/Vitreous.git
cd Vitreous
npm install
npm run dev        # launch Vitreous in development (hot reload)

npm scripts

Script	What it does
`npm run dev`	Launch the app in development with hot reload (`electron-vite dev`)
`npm run build`	Build main/preload/renderer bundles (`electron-vite build`)
`npm run preview`	Preview a production build locally
`npm test`	Run the unit tests (`node --test`)
`npm run dist`	Build + package the Windows NSIS installer → `release/`
`npm run dist:dir`	Build an unpacked app dir (fast, no installer)
`npm run pack:ext`	Zip the browser extension (Chrome) for the store
`npm run pack:ext:firefox` / `pack:ext:all`	Package the extension for Firefox / all targets
`npm run build:logo`	Regenerate app branding assets from the master logo
`npm run build:ext-icons`	Regenerate extension icons from the app master

Some flows (hosts writes, the scheduled-task helper, app killing) require Windows + admin and can't be exercised by the unit tests — those are verified live.

Project structure

Vitreous/
├─ src/
│  ├─ main/            # Electron main process (Node) — the enforcement core
│  │  ├─ enforce.js        # pure desired-block logic (unit-tested)
│  │  ├─ schedule.js       # recurring time-window scheduling
│  │  ├─ lockdown.js       # mandatory locked-session logic
│  │  ├─ app-watcher.js    # process polling + kill-on-sight
│  │  ├─ scheduler-task.js # elevated Scheduled Task install/run
│  │  ├─ bridge.js         # loopback WebSocket bridge to the extension
│  │  ├─ history.js        # Reflections aggregation (events.jsonl)
│  │  ├─ updater.js        # electron-updater integration
│  │  └─ …                 # elevate, notify, storage, ipc, tick, etc.
│  ├─ preload/         # contextBridge IPC surface
│  └─ renderer/        # React UI (liquid glass)
│     ├─ pages/ components/ theme/ styles/ data/
├─ extension/          # Manifest V3 browser companion
├─ scripts/            # build helpers (logo, ext icons, packaging)
├─ site/               # GitHub Pages download page
├─ docs/               # design specs & plans
├─ .github/workflows/  # CI: installer build + Pages deploy
├─ electron-builder.json   # packaging config (NSIS)
└─ electron.vite.config.mjs

Building a release & code signing

npm run dist produces release/Vitreous Setup <version>.exe + auto-update metadata (latest.yml, .blockmap).
CI builds the installer on a clean Windows runner (.github/workflows/release.yml) — this is the prerequisite for SignPath Foundation code signing, which signs CI-built artifacts. See docs/signing-signpath.md for the full flow.

🔒 Privacy

Local-first by design: no server, no account, no telemetry. Settings and history never leave your machine. The only outbound requests are (1) the optional quote of the day (a public quotes API that sends nothing about you and falls back to a bundled list offline) and (2) update checks against the public GitHub release feed. Full statement: privacy policy.

🗺️ Roadmap

Website blocking · App blocking · Scheduling · Lockdown · Reflections
Packaging, NSIS installer, lock-safe auto-update
Public download page (GitHub Pages) + first release
Code signing via SignPath Foundation (application submitted — under review)
Publish the browser extension to the stores
Import/export of activity history
macOS / Linux support

The living plan lives in PROJECT-PLAN.md; design specs are in docs/.

🤝 Contributing

Issues and pull requests are welcome! For bugs and ideas, please open an issue. Since main is protected, contribute via a feature branch and a pull request.

👤 Author

Subhasis Biswal

📄 License

MIT — free to use, modify, and distribute.

Badges by shieldcn.dev. Inspired by the concept of focus blockers, but an original product — our own name, our own code, our own design. Not affiliated with any other blocker.

If Vitreous helps you focus, consider giving it a ⭐ — it helps others find it.

Name		Name	Last commit message	Last commit date
Latest commit History 94 Commits
.github/workflows		.github/workflows
assets		assets
docs		docs
extension		extension
public		public
scripts		scripts
site		site
src		src
test		test
.gitignore		.gitignore
Beam Light effects.txt		Beam Light effects.txt
Block List Page Stle.txt		Block List Page Stle.txt
CLAUDE.md		CLAUDE.md
Fluidglass.txt		Fluidglass.txt
LICENSE		LICENSE
PRIVACY.md		PRIVACY.md
PROJECT-PLAN.md		PROJECT-PLAN.md
README.md		README.md
electron-builder.json		electron-builder.json
electron.vite.config.mjs		electron.vite.config.mjs
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Vitreous

A free, open-source, local-first focus blocker for Windows — wrapped in an Apple-style liquid-glass UI.

📑 Table of contents

⬇️ Download & install