Reference // Genesis
JAMES Documentation
Complete reference for JAMES — the free local browser AI chatbot. Covers architecture, tools, backend selection, model switching, and privacy.
Overview
JAMES (Just A Machine, Engineered for Speech) is a browser-native AI chat interface. It runs a quantized language model entirely inside your browser using WebGPU or WASM — no server, no API, no data leaving your device.
Conversation state is persisted in IndexedDB. Model weights are cached by the browser after first download. Once cached, JAMES works completely offline.
Model Loading
On first launch, JAMES downloads model weights from Hugging Face. This is a one-time operation — weights are cached by the browser indefinitely.
Model files are fetched in parallel chunks and cached locally, so the download can recover gracefully and load faster on future launches.
The progress bar at the top of the terminal reflects download progress. Status transitions are:
downloading → streaming → complete → done
Backends
JAMES selects the best available execution path for your hardware and automatically falls back if a preferred backend is unavailable.
WebGPU — primary (GPU)
The preferred high-performance backend for Chrome/Edge with a compatible GPU. JAMES tries progressively larger models based on your available VRAM.
GPU models (WebGPU / q4f16): Qwen2.5 0.5B — ~400 MB (auto-select) SmolLM2 1.7B — ~950 MB (auto-select) Llama 3.2 1B — ~750 MB (auto-select) Qwen2.5 1.5B — ~950 MB (auto-select) Llama 3.2 3B — ~2.1 GB (auto-select) Gemma 3 1B — ~600 MB (manual only) DeepSeek-R1 1.5B — ~1 GB (manual only) Phi-3.5-mini 3.8B — ~2.2 GB (manual only)
WASM — CPU fallback
Used when WebGPU is unavailable. Slower but compatible with any modern browser.
CPU models (WASM / q4 or q8): Llama 3.2 1B — ~650 MB TinyLlama 1.1B — ~600 MB Qwen2.5 0.5B — ~400 MB SmolLM2 1.7B — ~950 MB
Threads
Each conversation is a thread in the sidebar. Threads represent independent context histories and are saved locally.
- Click + New Chat to start a fresh session.
- Thread titles are derived from the first user message.
- Use the × button to delete a thread permanently.
- The active thread state is stored in localStorage and restored on revisit.
Stop Generation
The stop button terminates the worker and restarts generation state.
- Worker is terminated immediately.
- Partial streamed text is saved if available.
- The model restarts from the browser cache.
Python Execution
JAMES can execute Python code in-browser via Pyodide. Ask JAMES to run a Python calculation and it
will use the python tool automatically:
```tool:run python code: import math; print(math.factorial(20)) ```
Execution results are returned into the conversation and used to answer your query. Pyodide loads on first use; subsequent calls are instant.
Tool Reference
JAMES uses model-driven tool calling. When you ask a question that needs live or external data, the model emits a tool call block, the app executes it, and feeds the result back to the model for a final answer:
```tool:run weather location: Tel Aviv ```
Information Tools
Gets current weather conditions via Open-Meteo (no API key needed).
weather location: Tel Aviv
Fetches a Wikipedia article summary.
wikipedia query: Bijective numeration
Converts currency amounts via frankfurter.app.
currency from: USD, to: EUR, amount: 100
Returns current time for an IANA timezone.
time timezone: Asia/Jerusalem
Date utilities: now, diff, convert, parse.
date action: diff, date: 2025-01-01, date2: 2026-01-01
Returns a DuckDuckGo search link for a query.
websearch query: best local AI models 2025
Looks up IP geolocation info.
ip target: self
Utility Tools
Generates cryptographically secure UUIDs.
uuid count: 3
Creates strong random passwords.
password length: 24, count: 1, symbols: true
Generates color palettes from a base color.
palette base: #00ff41, scheme: triadic, count: 5
Starts a countdown timer with a visible widget.
timer seconds: 1500, label: Pomodoro
Evaluates a math expression safely.
calculator expr: (12 * 8) / 3 + sqrt(144)
Converts units (length, weight, temperature, speed, etc.).
convert value: 100, from: km, to: miles
Encodes or decodes Base64 strings.
base64 mode: encode, input: Hello World
Hashes a string using SHA-256, SHA-512, or MD5.
hash algorithm: sha256, input: hello
Converts between HEX, RGB, and HSL color formats.
color input: #ff6b6b
Generates random numbers, dice rolls, or coin flips.
random mode: dice, count: 2, sides: 6
Calculates time remaining to a target date.
countdown target: 2027-01-01
Runs Python code in Pyodide and returns stdout output.
python
code: print('Hello from Python')
Processes uploaded file content.
file filename: data.txt, content: ...
Searches a local Orama knowledge index seeded with JAMES documentation.
search query: browser inference
Device Tools
Reads clipboard text (requires user permission).
clipboard
Returns GPS coordinates (requires user permission).
location
Architecture
postMessage() → Storage → IndexedDB / localStorage
The worker owns inference and model state. The main thread owns the UI, tools bridge, and storage.
Privacy Model
JAMES is designed so no conversation data leaves your browser unless you explicitly request external information via tools.
| Data | Where it lives | Network exposure |
|---|---|---|
| Conversation messages | IndexedDB | None |
| Session metadata | IndexedDB / localStorage | None |
| Model weights | Browser cache | One-time download |
| Static assets | Service Worker cache | One-time download |
| Inference compute | Web Worker | None |
Service Worker
The service worker caches static app assets as an enhancement. Model weights bypass the SW and use the browser cache instead.
- App logic: network-first.
- CDN assets: cache-first.
- Model weights: browser cache.