Architecture & Portability

1. Static Web Architecture & Unified Backend

ZeroChat is built on a fundamental premise: maximum simplicity, speed, and control without heavy dependencies.

The web application is served directly and statically over HTTPS from GitHub Pages as zerochat.html, loading modular css/ and js/ files with no build step. Its Service Worker reuses available resources but does not replace a connection when one is needed.

All local system interaction is channeled through the zerochat executable installed from PyPI or the zerochat.py script. Both open the same GitHub Pages interface and authenticate sessions using secure daily tokens.

Key advantage: No bundlers, compilers, or build pipelines. The web application runs statically and the local backend runs on any system with a single terminal command.

2. Launch Modes: zerochat.html (Web) vs. zerochat.py (Local Backend)

ZeroChat is designed to deliver two complementary experiences depending on the workflow context: an autonomous universal web application (ideal for mobile devices and zero-install daily usage) and a local workstation host (for developer workflows requiring direct operating system control).

A. The Standalone Web Version (`zerochat.html`)

Accessible directly online (via GitHub Pages) or by opening the HTML file locally in any browser. It is a complete, self-contained application that requires neither Python, terminal commands, auxiliary servers, nor installation.

Universal web experience: Engineered as an installable Progressive Web App (PWA) in modern browsers, with a touch-friendly drawer sidebar and auto-expanding composer. No Python, root access, or terminal tools are needed.
Universal Multi-Model Connectivity: Connects directly from the browser to commercial cloud AI providers (OpenAI, Anthropic Claude, Google Gemini, OpenRouter) as well as CORS-enabled local network endpoints (Ollama, LM Studio).
Private In-Browser Local Inference (WebLLM / WebGPU): Downloads and executes open-source LLMs directly on your device GPU with WebGPU, ensuring absolute data privacy without sending messages over the wire.
Integrated Document RAG Knowledge Engine: Vector and lexical indexing of PDFs, Markdown, and text files using Orama running entirely inside Web Workers and persisted in IndexedDB.
Browser-Sandboxed Agent Mode: Autonomous multi-turn loop capable of executing JavaScript code in a 3-layer isolated sandbox (opaque null-origin iframe, restrictive network-blocking CSP, and Web Worker with watchdog termination), rendering interactive SVG charts, performing web searches, and fetching public web pages.
Total User Data Sovereignty: Conversations, branches, attachments, and configurations reside exclusively in your browser's private IndexedDB storage.

B. What the Local Backend Adds (`zerochat.py`)

Tailored for desktop workstations (Linux, macOS, Windows) where an agent needs to act as a coding assistant with access to the host operating system. It has also been tested on Android through Termux:

Host File System Control: Inspect directory structures, read workspace source code, and apply atomic or chunk-level file modifications on the local disk (read_file, edit_file, list_directory).
Terminal Command Execution: Run build tools, test runners, scripts, and shell commands in the host terminal environment (execute_command).
External MCP Server Ecosystem: Integrate Model Context Protocol servers to expand agent capabilities (headless browser automation with Playwright, LSP static analysis servers, SQLite relational storage).
Automated Environment Management: A single ~/zerochat/ directory contains the token, configuration, and services. Python dependencies are isolated in ~/zerochat/.venv/, without changing global Python.

Feature Comparison Matrix

Feature / Capability	`zerochat.html` (Web / PWA)	`zerochat.py` (Local Backend)
Commercial AI API connections (OpenAI, Claude, Gemini, etc.)	✅ Yes	✅ Yes
100% In-browser local inference via WebLLM & WebGPU	✅ Yes	✅ Yes
In-browser Document RAG Knowledge Base (Orama)	✅ Yes	✅ Yes
Agent Mode with JS sandbox, web search & SVG charts	✅ Yes	✅ Yes
Private IndexedDB persistence and JSON/Markdown export	✅ Yes	✅ Yes
Direct usage on Mobile (Android / iOS) without Python/terminal	✅ Native (PWA)	⚠️ Requires Python (Termux or desktop)
Host file system navigation, reading and atomic editing	❌ Not available	✅ Yes (host tools)
Host terminal shell command execution	❌ Not available	✅ Yes (bash/shell)
External MCP servers (Playwright, memory, LSP)	❌ Not available	✅ Yes (integrated MCP manager)

3. Static Web Delivery & Local Backend Connectivity

ZeroChat is distributed as a universal static web application:

Universal Web Delivery (HTTPS): Served directly from GitHub Pages (https://albalday.github.io/zerochat/zerochat.html). All interface rendering, agent execution, and inference calls happen in the browser with full access to modern web APIs like navigator.storage.persist() and private local IndexedDB storage.
Unified Local Backend: Running zerochat after installing it from PyPI, or python3 zerochat.py after downloading the script, launches the local server on 127.0.0.1:6388 and opens GitHub Pages. The app consumes the session token only once, removes it from the address bar, and retains it in a cookie on the same web origin.

Automatic local development & testing: When running python3 zerochat.py directly inside the cloned repository, it automatically detects the development environment and serves the local interface at http://127.0.0.1:6388/zerochat.html without requiring auxiliary servers or launch scripts.

How to run tests:

python3 zerochat.py: Starts the backend and automatically opens the local development web UI in the default browser.
python3 zerochat.py --test: Runs quick internal self-tests for core host tools (file reading, directory listing, command execution).
npm test: Runs the full automated test suite (unit, integration, architecture, infrastructure, and Playwright browser tests).
npm run test:browser: Runs only browser and visual UI tests.

4. Local infrastructure, distribution, and updates

Installation with pip install zerochat distributes only the Python executable. The direct download distributes that same executable as zerochat.py. Neither includes HTML, JavaScript, or CSS: both open the GitHub Pages interface, so web storage and the session cookie share one origin.

In the user's home directory, both modes create the same structure:

~/zerochat/
├── .venv/       Isolated environment for Python MCP dependencies
├── config/      Token and service preferences
└── services/    MCP servers and their dependencies

The PyPI executable remains managed by pip and the downloaded file remains where you saved it. Deleting ~/zerochat/ removes local state and MCPs without touching either executable.

Versions use major.minor.patch. A patch updates only the GitHub Pages interface; 7.11.0 is compatible with 7.11.x. A move from 7.11 to 7.12 updates the backend: ZeroChat reports it and displays the appropriate command, python -m pip install --upgrade zerochat for PyPI or the zerochat.py download for curl.

Technical reports

ZeroChat 7.11.0 audit (25 September 2026), with local evidence and verification limits:

Features and maturity report: verified inventory, MCP and RAG scope, and test coverage.
Comparison with similar tools: positioning, strengths, limitations, and selection criteria.
Code quality and infrastructure report: metrics, risks, local security, and an improvement plan.

5. Local Storage & Data Privacy

ZeroChat's storage architecture strictly respects user data sovereignty. The application never transmits conversation history, credentials, or documents to any telemetry backend.

Client-side storage layers:

IndexedDB (ZeroChatDB): Structured browser database storing chat sessions, messages, metadata, user profile configurations, and local RAG branches.
Isolated Attachment Store: Large Base64 images and uploaded documents are isolated in dedicated IndexedDB object stores to keep the active message tree fast, responsive, and lightweight.
Cache Storage API: Used by WebLLM to persist downloaded local model weights and shader modules.
LocalStorage / Session Cookies (ChatStorage): Manages UI state and interface preferences (such as the active color theme).

6. Canonical State (ChatState)

To prevent memory leaks or state desynchronization across components, ZeroChat uses a single canonical state store: ChatState.

Every lifecycle change (switching sessions, appending streamed tokens, tracking inference progress, or executing tools) occurs through domain mutators (such as appendMessage, replaceMessages, or saveSessionMetadata). This ensures reactive, synchronized updates throughout the UI.

7. Shared conversation rules

New and restored responses share visual block and copy components. Streaming retains its cursor during generation. Connection errors use a common view that escapes the received message and URL before inserting them into HTML.

Active configuration comes from ChatConfig. Profile and catalog interfaces query the WebLLM provider for completed models instead of independently parsing stored metadata.

State, engine and views reuse message-turns.js rules to identify turns and recognize initial date messages. Turn removal shares a sanitization algorithm; ChatState retains the generation guard and atomic history update.