🧠

How HelperBrain works

the whole stack runs in your browser tab — this page is the tour

HelperBrain has no backend. The page you load is static files; everything that happens after that happens on your machine:

helperbrain.org (static files on a CDN — that's the entire "infrastructure")
├── index.html                     UI + wiring only
├── helperbrain_harness.wasm       the decision engine (Rust → WebAssembly)
├── webllm.js                      WebLLM runtime (vendored, same origin)
└── model/…  (~0.7 GB, one-time)   Llama 3.2 1B, 4-bit, runs on YOUR GPU via WebGPU

Every request goes to helperbrain.org — the model shards, the runtime, the wasm. No third-party CDN, no API, no analytics. Open DevTools → Network and watch.

The design rule that makes a 1B model reliable

Language → the model. State, arithmetic, and identifiers → code. A small model is only ever asked to do the one thing small models are good at: turn your words into structured suggestions. Everything that has to be correct lives in the Rust→WASM harness:

the model suggests…	the harness guarantees…
how to sort your brain dump into buckets	every line you typed survives (a coverage check re-adds anything the model dropped); bucket names are coerced onto the real enum
minutes per task	clamped 2–240; absurd values replaced by a deterministic heuristic; totals computed in code
micro-steps for a scary task	3–8 steps, numbering stripped, length-capped — or a built-in fallback breakdown
which tasks move your long-term goals	fabricated task/star ids are dropped; links only ever point at real state
warm words for check-ins and the weekly digest	every number in the digest is computed from local logs, never generated

The time math is fully deterministic: your "ADHD buffer" is the median of actual ÷ guessed time from your own history (clamped 1–3×) plus a fixed transition cost. The focus timer's default length is whichever block length your history shows you actually complete. No model in that loop at all — and if the model never loads, keyword fallbacks run the whole app in "instant mode."

What runs where

layer	what it is	size
UI	one HTML file: rendering, WebAudio (chimes + generated brown noise), confetti, timers' rAF loop	~55 KB
Harness	Rust compiled to wasm32: task state, parsers, guards, buffer math, streaks, dopamine deck, prompts	~360 KB
LLM runtime	WebLLM (MLC), vendored	~6.5 MB
Model	Llama 3.2 1B Instruct, 4-bit quantized, executing on your GPU via WebGPU	~0.7 GB, cached

Model outputs are JSON-schema-constrained (the grammar makes malformed output impossible), then still guarded. All prompts are assembled inside the wasm from live state, so the model only ever sees ids that actually exist.

Verify the privacy claim yourself

Open DevTools → Network. Use the app, vent something, complete tasks. Every request stays on helperbrain.org; after the model is cached, there are essentially none at all.
Your data lives in localStorage under helperbrain-state — inspect it (Application tab), it's plain JSON. The vent chat is deliberately not in there: it's never persisted anywhere.
Backups are encrypted client-side: PBKDF2-SHA256 (310k rounds) → AES-256-GCM via WebCrypto. The blob is yours to email around; without the passphrase it's noise.
Turn off Wi-Fi after your first visit. The app (installed as a PWA, or a cached tab) keeps working — including the model.

Honest limits

The brain needs WebGPU (Chrome/Edge today) and a real GPU — software renderers get instant mode instead of a model running at unusable speed.
A 1B model's prose is serviceable, not brilliant. That's precisely why the harness, not the model, makes every decision that has to be right.
Your data lives in one browser unless you carry it: encrypted backup out, restore in. No sync, by design — sync means servers, servers mean trust.

Stack: Rust + wasm-bindgen, WebLLM/MLC, Llama 3.2 1B (Meta, MLC 4-bit build), WebGPU, WebCrypto, Cloudflare R2 for static hosting. The harness ships with native unit tests, a Node smoke test that drives the real wasm artifact, and a headless-browser suite that exercises the entire no-model path.