Skip to content

CLAUDE.md

Latest commit

 

History

History
68 lines (50 loc) · 2.72 KB

CLAUDE.md

File metadata and controls

68 lines (50 loc) · 2.72 KB
Raw

CLAUDE.md

Guidance for Claude Code working in this repository. Source of truth for decisions is PROJECT-PLAN.md — read it before planning work, and update it when decisions change.

What this is

A free, open-source, locally-run focus blocker for desktop (Windows first). It blocks distracting websites (apps later) on demand or on a schedule. The signature differentiator is a modern, Apple-style "liquid glass" UI.

  • Runs entirely on the user's machine — no backend, no server, no accounts.
  • All settings / block-lists stored in a local file (e.g. JSON).
  • Distributed via a public GitHub repo, GitHub Releases, and a GitHub Pages download page.
  • Name: Vitreous (decided — "vitreous" = glasslike, fits the liquid-glass identity).

Status: app shell in active development (Electron + Vite + React).

Tech stack (decided)

Layer Technology
App shell Electron
UI HTML + CSS (the "liquid glass" look)
Interactivity JavaScript, likely React
OS / enforcement Node.js (bundled with Electron)
Storage Local file (JSON)

Website enforcement on Windows is expected via the system hosts file and/or a browser helper — exact approach still to be designed.

Build order (phases)

  1. Website blocking — start here (block sites like youtube.com).
  2. App blocking — future.
  3. Scheduling (recurring blocks) — to discuss.
  4. "Hard to bypass" lockdown — to discuss.

Ship in solid, working steps rather than one large half-working version.

Rules — must follow

Legal safety (non-negotiable):

  • Do NOT use the name "Cold Turkey", its logo, or its branding.
  • Do NOT copy its code, icons, or exact layouts.
  • Do NOT claim any affiliation.
  • DO use our own name, code, and original design. Inspiration from the concept is fine. Rule of thumb: same idea, our brand, our code, our design.

Product principles:

  • Free for everyone — no paywall, no subscription.
  • Beautiful design is a first-class requirement, not an afterthought.
  • Local-first and private by design — never add a server or online account.

Working agreements

  • PROJECT-PLAN.md is a living document — keep it in sync as decisions are made, and respect its ✅ decided / ⬜ to-decide / 🔜 future markers.
  • Don't introduce a server, telemetry, or paid tier — these contradict core goals.
  • When a decision is still ⬜ open (name, license, scheduling behavior, lockdown strictness, cross-platform), confirm with the user before assuming.

Commands

No build/test tooling exists yet. Add commands here once the Electron project is scaffolded (e.g. npm install, npm start, packaging via electron-builder).