README.md

metadata

title: MiniCPM5 WebGPU Workspace
emoji: 🥧
colorFrom: green
colorTo: blue
sdk: static
app_file: index.html
pinned: false
license: apache-2.0
short_description: A local coding agent with a GGUF WebGPU runtime
models:
  - openbmb/MiniCPM5-2B-GGUF
tags:
  - webgpu
  - gguf
  - text-generation
  - agents
  - just-bash

MiniCPM5 WebGPU workspace

A clone of victor/MiniCPM5-2B-WebGPU-Pi, with the supplied minicpm5.js and agent.js replacing Transformers.js, ONNX Runtime, and Pi's agent core. The original Pi terminal interface, editor, cat mascot, shell, and virtual file workspace are preserved.

Deploy to Hugging Face Spaces without a build

Create a Static Space, extract this ZIP, and upload its contents directly to the Space repository root. Keep README.md, index.html, assets/, src/, runtime/, vendor/, icons, images, and license files in their existing relative locations. This README already declares sdk: static and app_file: index.html.

No build command, npm install, or dist/ directory is required. The editable integration source runs directly as ES modules, and the upstream UI assets are already built. npm run build is optional: it only copies the runnable files to dist/ for hosts that expect a distribution directory.

The ZIP also contains optional local server/build scripts, tests, and API docs. Model weights download on first use and are not included.

Run locally

Requires Node.js 20+ to serve files. No npm dependencies or installation step.

npm start

Open http://127.0.0.1:5173 in a browser with WebGPU. Alternatively, serve the project directory using any static HTTP server. Use HTTPS when hosting remotely. file:// does not work. A recent Chrome or Edge with sufficient GPU memory is the runtime's documented target; this integration has not been tested on Safari.

Click Load model, or send a message and confirm the download. The default is openbmb/MiniCPM5-2B-GGUF/MiniCPM5-2B-Q4_K_M.gguf, approximately 1.6 GB. The runtime caches downloaded ranges in browser storage when available. This is a different weight format and cache from the original ONNX demo.

The app asks for confirmation before loading, including on later visits. The runtime has no public complete-cache/cache-only check, so the app cannot promise that a cached reload makes zero weight requests. Available cached ranges are still reused. Browser storage availability and eviction are browser-dependent.

Once loaded, prompts, model inference, tools, and files stay in the browser. Weights are downloaded from Hugging Face; no inference API or API key is used. The shell has no network, Python, Node.js, npm, or native binaries.

Try: What's our total sales revenue? The starter CSV and product prices give $144; ask the agent to inspect the files and write a report.

Controls

• Enter sends a message; Shift+Enter adds a newline.
• Stop, Escape, or Ctrl+C cancels generation and signals the active tool.
• /load, /new, /help, and !ls work in the terminal.
• Read, write, edit, and bash tools operate on a virtual filesystem.
• Import accepts text files; Export downloads a workspace JSON snapshot.
• Files and conversations persist in IndexedDB when browser storage is available.

The agent uses greedy decoding, automatic thinking, up to 4,096 new tokens per reply including reasoning, and at most 12 replies per run. It requests an 8,192-token context; the runtime may lower that to fit the GPU. The UI shows the actual capacity. A full context produces a clear error; use New chat to continue with the same files. Histories are not silently truncated.

Cancelled partial replies remain visible but are omitted from the canonical model history, matching the supplied Agent's behavior. Finished tool calls and their results stay in history. Exact decode speed is reported from the runtime's completed-turn timings; streaming deltas do not expose token counts.

Project layout

Path	Purpose
index.html, assets/	Original built UI, with the new worker URL and updated runtime metadata.
runtime/minicpm5.js	Supplied GGUF/WebGPU model implementation, unchanged.
runtime/agent.js	Supplied model-independent agent loop, unchanged.
src/agent.worker.js	Worker entry point and RPC transport.
src/controller.js	Loading, events, conversation lifecycle, cancellation, and saves.
src/conversation.js	Display-only adapter for Pi terminal messages and progress.
src/workspace.js	Shell tools, virtual filesystem, serialization, IndexedDB.
src/config.js	Model, context/token limits, and instructions.
vendor/just-bash.js	Shell and its dependencies extracted from the upstream worker.
scripts/	Dependency-free local server and static build.
test/	Node tests using real shell/tools and the supplied Agent with fake model sessions.
docs/runtime-api.md	README from the supplied archive.
docs/integration.md	Integration notes, provenance, and verification limits.
licenses/, NOTICE, LICENSE	Original notices and retained attribution.

The upstream repository only ships built UI assets; it does not include the original UI source or source maps. The preserved UI therefore remains a compiled asset. The replacement worker and integration code are editable ES modules.

Validate and build

npm test
npm run build

dist/ contains the static app. The project root also works directly in a Hugging Face static Space using the metadata above; no server or build service is required. Model weights are not included in this project or its ZIP.

Tests cover integration behavior without loading model weights. Actual WebGPU inference and visual browser checks were unavailable in the implementation environment; those remain to be run on a WebGPU device. No performance or model quality claim is made from the mocked tests.