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