{"id":"823354d7-683a-47d6-bc98-bc1d9e106b6a","slug":"numkit","kind":"mcp","name":"numkit","summary":"MATLAB-compatible runtime for humans & AIs","owner":"hotredman","repoUrl":"https://github.com/hotredman/numkit","license":"0BSD","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-08-15T21:06:17.000Z","addedAt":"2026-10-21T04:58:53.621Z","logoUrl":"https://avatars.githubusercontent.com/u/299806118?u=4906ce722dd6729bd4e483dd23eaf33dc251dc94&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","communication","cloud-infra"],"tags":["matlab","vibe-coding","npm","ai-agent","claude-desktop","cli","cpp17","dsp"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T05:00:15.577Z","sample":false,"url":"https://conduits.dev/tools/numkit","language":"C++","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Lightweight numerical computing engine & MATLAB-compatible runtime\n\n[![License: 0BSD](https://img.shields.io/badge/License-0BSD-blue.svg)](LICENSE)\n[![Live Demo](https://img.shields.io/badge/Web_IDE-Live_Demo-success.svg)](https://hotredman.github.io/numkit-demo/)\n[![Bugs & Parity](https://img.shields.io/badge/Bugs_%26_Parity-Catalog-orange.svg)](https://hotredman.github.io/numkit-bugs/)\n[![SAST: PVS-Studio](https://img.shields.io/badge/SAST-PVS--Studio-01a8e5.svg)](bugs/pvs/summary.md)\n[![npm](https://img.shields.io/badge/npm-numkit-red.svg)](https://www.npmjs.com/package/numkit)\n\nA lightweight numerical computing engine and matrix-scripting interpreter written in modern C++17. Designed from the ground up for **AI Agents, WebAssembly sandboxes, and embedded C++ applications**, it delivers MATLAB/Octave compatibility with instant startup and zero external dependencies.\n\n👉 **Try it in your browser:** [https://hotredman.github.io/numkit-demo/](https://hotredman.github.io/numkit-demo/)  \n👉 **C++ Library Documentation:** [https://hotredman.github.io/numkit-doxy/](https://hotredman.github.io/numkit-doxy/)  \n👉 **Defect & Parity Catalog:** [https://hotredman.github.io/numkit-bugs/](https://hotredman.github.io/numkit-bugs/)  \n👉 **Static Analysis Report (PVS-Studio):** [`bugs/pvs/summary.md`](bugs/pvs/summary.md)  \n👉 **LLM / Agent context spec:** [`llms.txt`](ide/public/llms.txt)\n\n---\n\n## Coding Agents\n\n[![Claude](https://img.shields.io/badge/Claude-Anthropic-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://claude.ai)\n[![Gemini](https://img.shields.io/badge/Gemini-Google_DeepMind-8E75C2?style=for-the-badge&logo=google-gemini&logoColor=white)](https://deepmind.google/technologies/gemini/)\n[![Z.ai](https://img.shields.io/badge/Z.ai-ZCode-1E88E5?style=for-the-badge)](https://z.ai)\n\nEngineered in continuous pair-programming with autonomous AI coding agents (Claude, Gemini, Z.ai). Each agent co-authors and signs its work with a dedicated `Co-Authored-By` Git trailer.\n\n---\n\n## SAST Tools\n\n[![PVS-Studio](https://img.shields.io/badge/PVS--Studio-SAST%20Verified-01a8e5?style=for-the-badge)](https://pvs-studio.com/pvs-studio/?utm_source=website&utm_medium=github&utm_campaign=open_source)\n\n[PVS-Studio](https://pvs-studio.com/pvs-studio/?utm_source=website&utm_medium=github&utm_campaign=open_source) - static code analyzer for Enterprise (C, C++, C#, Go, and Java) and Web (JS and TS) development.\n\n---\n\n## 🎯 Project Goal — Run the Books\n\nThe compatibility target is concrete, not aspirational: **every companion script from the textbooks catalogued in [awesome-matlab-books](https://github.com/hotredman/awesome-matlab-books) must run unmodified** — the ~922,000 lines of MATLAB across 78 repositories spanning robotics, signal & audio processing, control systems, image processing, wireless/SDR, machine learning, numerical methods, and finance.\n\nHow the goal drives development:\n\n- The catalog's empirical function-usage statistics (which built-ins real book code actually calls) prioritise toolbox coverage — the long tail is implemented demand-first, not alphabetically.\n- The `fieldtest/` harness runs each book's scripts against the engine and diffs results against MATLAB R2025b, turning \"MATLAB-compatible\" into a measured per-book pass rate.\n- Every divergence found this way is filed in the structured [bug catalog](bugs/README.md) with a self-contained repro and a regression guard, then fixed at the root — no silent gaps.\n\nStatus so far: the *Signals and Systems* book's examples pass end-to-end (19/19 non-symbolic; the 2 symbolic-toolbox examples are out of scope by decision), and graphics handles (`h = plot(...)`, `set`/`get`, dot-syntax) now match MATLAB semantics for the plot family.\n\n---\n\n## 🤖 Built for AI Agents & LLMs\n\nModern AI coding agents (Claude, Cursor, Antigravity, AutoGen, LangChain) need to execute mathematics, DSP, and numerical analysis reliably. Running Python/Jupyter in Docker is heavy, slow to boot, and token-expensive. This runtime provides the ideal execution environment for agent tool-calling loops:\n\n* ⚡ **Instant Startup (< 1 ms)** — Zero cold-start latency compared to 300–800 ms for Python / Jupyter runtimes.\n* 🪙 **Token-Efficient Syntax** — Native matrix operations (`A \\ b`, `[b, a] = butter(4, 0.2);`, `fft(x)`) require 2–3× fewer tokens than Python imports and boilerplate, preserving context window and reducing LLM syntax mistakes.\n* 🛡️ **Zero-Install WASM Sandbox** — Runs safely in-process via WebAssembly (Node.js / browser) without requiring Docker containers, root privileges, or local compilers.\n* 🔌 **Agent & Tool-Calling Native** — Ready for CLI execution, Model Context Protocol (MCP), and structured JSON output.\n\n### 1-Line Execution for Agents (Zero Install, WASM)\n\n```bash\n# Instant calculation via npx (Node >= 16, no native compiler required):\nnpx -y numkit -e \"A = [1 2; 3 4]; disp(A \\ [5; 11])\"\n\n# Run full scripts:\nnpx -y numkit script.m\n```\n\n### Why AI Agents Choose This Runtime over Python\n\n| Feature | Python (NumPy / SciPy) | This Runtime |\n| :--- | :--- | :--- |\n| **Startup Latency** | 300–800 ms (cold start) | **< 1 ms (instant)** |\n| **Isolation / Sandbox** | Heavy Docker / gVisor container | **In-process WebAssembly / C++** |\n| **Footprint & Deps** | 500 MB+ (Python env, pip, glibc) | **5 MB standalone WASM / Single binary** |\n| **Token Efficiency** | Verbose imports & ceremony | **Compact matrix-native DSL** |\n| **Deterministic Safety** | Unhandled segfaults in native C extensions | **StackGuard & memory-safe runtime** |\n\n---\n\n## Key Features\n\n- **Matrix-Oriented Scripting**: Column-major multidimensional arrays, complex numbers, cell arrays, structs, and function handles with copy-on-write (COW) memory semantics.\n- **Dual Execution Engine**: Fast non-recursive bytecode virtual machine with AST TreeWalker fallback and interactive step-debugger (breakpoints, step over/in/out, paused workspace inspection).\n- **Extensive Numerical Toolboxes**:\n  - **Math & Linear Algebra**: Arithmetic, trigonometry, special functions, polynomials, LU, QR, Cholesky, SVD, eigenvalue solvers.\n  - **Signal & Audio**: FFT/IFFT, digital filtering (`filter`, `filtfilt`, Butterworth/Chebyshev design), spectral analysis, WAV I/O.\n  - **Statistics**: Distributions, descriptive statistics, regression, hypothesis tests, PCA.\n  - **Image Processing**: Color conversions, spatial filtering, morphology, geometry, image I/O (PNG, BMP, JPEG).\n  - **Control Systems & Wavelets**: LTI models, state-space representations, Bode/Nyquist responses, continuous & discrete wavelet transforms.\n  - **Optimization & ODE**: Root finding (`fzero`), bounded/unconstrained optimization (`fminbnd`, `fminsearch`), Runge-Kutta ODE solvers.\n  - **File I/O**: MAT-file (v5) read/write, CSV, delimited text, audio/image formats.\n- **AOT C++ Codegen**: Transpiles scripting code directly to optimized native C++ with SIMD acceleration (Highway).\n- **Web & Desktop IDE**: Interactive workspace featuring code editor, variable viewer, 2D/3D figures (SVG & WebGL), and REPL console (available in browser via WebAssembly and as a desktop application via Electron).\n\n---\n\n## Quickstart\n\n### C++ Embedding\n\n```cpp\n#include <iostream>\n#include <nk/bundle/standard_engine.hpp>\n\nint main() {\n    nk::StandardEngine engine;\n\n    engine.eval(\"A = [1, 2; 3, 4];\");\n    engine.eval(\"b = [5; 11];\");\n    engine.eval(\"x = A \\\\ b;\");\n    engine.eval(\"disp(x);\");\n\n    return 0;\n}\n```\n\n---\n\n## Building\n\n### Prerequisites\n\n- **C++ Engine**: C++17 compatible compiler (GCC 9+, Clang 10+, MSVC 2019+), CMake 3.21+, Ninja (recommended for Linux/macOS)\n- **Web & Desktop IDE**: Node.js 18+ and npm\n- **WebAssembly Engine** *(optional)*: [Emscripten SDK](https://emscripten.org/) (`EMSDK` environment variable)\n\n---\n\n### Native Engine & CLI\n\nYou can build either using automated helper scripts or standard CMake presets:\n\n#### Option A: Quick build via scripts\n\n```bash\n# Windows\nscripts\\windows\\engine-build.cmd             # Release (Highway SIMD + Threads)\nscripts\\windows\\tests-run.cmd                # Build & run Google Test suite\nscripts\\windows\\tests-run.cmd --gtest_filter=*Matrix*  # Run specific tests\n\n# Linux / macOS / WSL\n./scripts/linux/engine-build.sh              # Release (Highway SIMD + Threads)\n./scripts/linux/tests-run.sh                 # Build & run Google Test suite\n./scripts/linux/tests-run.sh --gtest_filter=*Matrix*\n```\n*Script flags:* `--debug` (debug symbols), `--portable` (scalar reference, no SIMD), `--wasm` (WebAssembly).\n\n#### Option B: Standard CMake Presets\n\n```bash\n# Configure & build\ncmake --preset windows-release               # On Linux: cmake --preset linux-release\ncmake --build --preset windows-release\n\n# Available presets: windows-release, windows-debug, windows-portable,\n#                    linux-release,   linux-debug,   linux-portable, wasm-release\n```\n\n#### Output Artifacts\n\nBinaries are located in `build/<os>/<config>/`:\n- `build/<os>/<config>/apps/nk/nk_repl` — Interactive MATLAB-compatible REPL and CLI runner (`nk_repl script.m`).\n- `build/<os>/<config>/apps/nk_codegen/nk_codegen` — C++ AOT code generator.\n- `build/<os>/<config>/tests/gtest/nk_gtest` — Google Test regression runner.\n\n---\n\n### Web & Desktop IDE\n\n#### Web IDE (WebAssembly + Vite)\n```bash\nscripts\\windows\\web-build.cmd    # Windows (outputs static bundle to deploy/web/)\n./scripts/linux/web-build.sh     # Linux / macOS\n```\n\n#### Desktop Application (Electron)\n```bash\nscripts\\windows\\desktop-build.cmd   # Packages Windows portable .exe\n./scripts/linux/desktop-build.sh    # Packages Linux AppImage and unpackaged dir\n```\n\nFor development servers, documentation generators, and deployment workflows, see [`scripts/README.md`](scripts/README.md).\n\n---\n\n## Repository Structure\n\n- `src/` — Core C++ interpreter, bytecode VM, value types, and domain toolboxes.\n- `ide/` — React + Vite IDE frontend and Electron desktop shell.\n- `wasm/` — Emscripten bindings and WASM build pipeline.\n- `examples/` — MATLAB-compatible demonstration scripts across all toolboxes.\n- `fieldtest/` — Book-corpus harness: fetches companion-code repos from the\n  [awesome-matlab-books](https://github.com/hotredman/awesome-matlab-books)\n  catalog, runs every script, and diffs against MATLAB (the corpus itself is\n  disposable and gitignored; see `fieldtest/README.md`).\n- `tests/` — Comprehensive C++ unit and integration test suite.\n- `tools/` — Parity testing harness, benchmarks, and validation utilities.\n- `bugs/` — Structured defect catalog, MATLAB parity tracking ([live catalog](https://hotredman.github.io/numkit-bugs/)), and [PVS-Studio reports](bugs/pvs/summary.md).\n- `dev-docs/` — Architecture documentation, memory records, and API guidelines.\n\n---\n\n## License\n\nThis project is open-source software released under the **[BSD Zero Clause License (0BSD)](LICENSE)**.\n\nYou are free to use, copy, modify, and distribute this software for any purpose, commercial or noncommercial, with or without fee, with no attribution required. See [NOTICE](NOTICE) for third-party component licenses.\n"}