Snowball

A local-first productivity hub for staying consistent — without the app-switching fatigue.

Features · Architecture · Preview · Get started · Installation · Status · License

Snowball replaces the daily juggle of a task manager, habit tracker, focus timer, and notes app with a single system — one source of truth for your routine on Windows, macOS, Linux, Android, and the web. Everything is stored locally first and synced to the cloud in the background, so the app stays fast and keeps working offline.

---

Features

Task Management

• Planning & execution: priorities, dates, and time blocks for your day.
• Progress tracking: completion counts and effort allocation per task.
• Tagging: custom, color-coded tags for effortless categorization.

Habit Tracking

• Consistency first: a dedicated tracker for daily habits.
• Visual momentum: an activity heatmap that shows your streaks over months.

Deep Work & Focus

• Focus timer: a built-in timer to cut out distractions and enter a flow state.
• Session tracking: logged focus hours feed into your productivity score.

Knowledge & Scratchpad

• Quick notes: a low-friction scratchpad for reminders, ideas, and temporary logs.
• Zero overhead: fast access to information without maintaining a full wiki.

Media Hub

• Spotify & YouTube: bring study/work soundtracks and tutorials straight into your focus environment.

Architecture

Snowball is built on a local-first philosophy: immediate responsiveness and offline availability come before constant network connectivity. For a deeper dive, see ARCHITECTURE.md.

Sync Engine

• Immediate UI (optimistic updates): every mutation is applied to local state and IndexedDB (via Dexie.js) instantly.
• Eventually consistent: changes are pushed to the cloud (Supabase) in the background.
• The outbox pattern: if a network request fails, the mutation is stored in a local outbox queue and replayed automatically when connectivity is restored.

Tech Stack

Layer	Stack
Frontend
Local storage
Backend
Database & auth
Desktop & mobile
Hosting

Preview

A tour of the current interface — click any image to open it at full size.

Plan and review

_{Full task board — priorities, dates, tags, and effort tracking}

_{Minimal task board}

_{History and productivity score}

Track and focus

Habits	Daily summary	Focus timer

Organize and connect

Calendar	Friends	Quick notes

Get Started

Run the app from source. Prerequisites: Node.js 22+ and git.

git clone https://github.com/Horrid-12/Snowball.git
cd Snowball
npm run install:all
cp backend/.env.example backend/.env
npm run dev

Windows PowerShell users

git clone https://github.com/Horrid-12/Snowball.git
cd Snowball
npm run install:all
Copy-Item backend\.env.example backend\.env
npm run dev

Before the backend can start, fill in backend/.env:

Variable	Required	Purpose
JWT_SECRET	yes	Signs auth tokens — any random string is fine in development
SUPABASE_URL	yes	Your Supabase project URL
SUPABASE_SERVICE_ROLE_KEY	yes	Server-side service role key — never expose it to clients
SUPABASE_ANON_KEY	yes	Anon key used for RLS-scoped, user-token queries
VITE_DISCORD_CLIENT_ID	no	Discord sign-in (frontend)

The app then runs at:

• Frontend: http://localhost:5173
• Backend: http://localhost:3000

Installation

Download a prebuilt app from Releases:

Platform	Download Artifact	Installation / Running
Windows	Snowball_*_x64-setup.exe	Run the installer and launch Snowball from the Start Menu.
macOS (Apple Silicon)	Snowball_*_aarch64.dmg	Open the.dmg, drag Snowball.app into Applications. (See Gatekeeper note below.)
macOS (Intel)	Snowball_*_x64.dmg	Open the.dmg, drag Snowball.app into Applications. (See Gatekeeper note below.)
Linux (Ubuntu/Debian)	snowball_*_amd64.deb	Runsudo apt install ./snowball_*_amd64.deb (or double-click to install).
Linux (Universal)	Snowball_*_amd64.AppImage	Runchmod +x Snowball_*.AppImage, then ./Snowball_*.AppImage.
Android	Snowball_*_Android.apk	Sideload and install the APK on your device.

Note

macOS first launch (Gatekeeper): Because Snowball is community open-source and not signed with an Apple Developer ID certificate ($99/yr), macOS will flag the app on first launch. To run it:

1. Right-click (or Control-click) Snowball.app in /Applications and select Open.
2. Click Open in the confirmation dialog.
3. Alternative: Go to System Settings → Privacy & Security, scroll down to Security, and click Open Anyway (or run xattr -cr /Applications/Snowball.app in Terminal).

Status

Current stage: active development. Features are added and refined frequently. Contributions and feedback are welcome — see Issues for current bugs and feature requests.

Contributing

Contributions, bug reports, and feature requests are all welcome:

1. Fork the repository and create a feature branch.
2. Make your changes — see Get Started to run the app locally.
3. Open a pull request describing what changed and why.

Report bugs and propose features in Issues. For security matters, follow SECURITY.md.

License

Distributed under the MIT License. See LICENSE for details.