VibeGuard

VibeGuard is a local-first browser extension that hides toxic social-media posts. Content is classified on-device; post text is never sent to a classification service.

Development

npm install
npm run typecheck
npm test
npm run build:firefox
npm run build:chromium

Each build writes a browser-specific package under dist/<mode>/. The packaged Apache 2.0 model is committed through Git LFS. Use the pinned-revision workflow below when updating it:

python3 -m venv .model-venv
. .model-venv/bin/activate
python3 -m pip install -r tools/requirements-model.txt

# Inspect architecture, labels, tokenizer, and resolved source revision.
python3 tools/convert_model.py inspect \
  --model wagesj45/toxic-comment-classifier

# Use the immutable commit printed by inspection for a release artifact.
python3 tools/convert_model.py prepare \
  --model wagesj45/toxic-comment-classifier \
  --revision <resolved-huggingface-commit>
python3 tools/convert_model.py validate

Preparation writes the Transformers.js-compatible files and model-manifest.json under public/models/toxicity/. The manifest records the source revision, Apache 2.0 license, toxic/non-toxic label indices, maximum sequence length, and int8 quantization format. Source PyTorch/safetensors weights are never copied into the extension.

If the model uses generic labels such as LABEL_0 and LABEL_1, pass --toxic-index and --non-toxic-index to prepare; the command refuses to guess an ambiguous mapping.

The first release targets Reddit, X/Twitter, and Facebook. Site selectors are isolated under src/content/parsers/ because these sites frequently change their DOM structures.

Runtime architecture

Firefox uses a persistent MV2 background page and inference worker. Chromium uses an MV3 service worker as a router, an offscreen document, and a worker-backed classifier. Both builds share one bounded, prioritized inference queue and in-memory text-result cache.