---
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](https://huggingface.co/spaces/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.

```sh
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

```sh
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.