diff --git a/npm/README.md b/npm/README.md
new file mode 100644
index 0000000..553171e
--- /dev/null
+++ b/npm/README.md
@@ -0,0 +1,12 @@
+# quicksilverpro (npm launcher)
+
+```bash
+npx quicksilverpro setup        # sign in, install the QuickSilver skill + MCP into your agents
+npx quicksilverpro box ls       # your cloud dev boxes
+```
+
+This package is a thin launcher for the [QuickSilver Pro CLI](https://github.com/machinefi/qspro-cli) (`qsp`), a Python tool. It runs the matching version through [uv](https://docs.astral.sh/uv/) (`uvx`), or pipx if uv is missing.
+
+- One OpenAI-compatible API for frontier and open models: https://quicksilverpro.io
+- QuickSilver Machines: cloud dev boxes with Claude Code, Codex, OpenCode and Hermes ready out of the box. Agents ready out of the box. One unified bill. Zero friction.
+- Docs: https://quicksilverpro.io/docs/machines/cli/
diff --git a/npm/bin/qsp.js b/npm/bin/qsp.js
new file mode 100755
index 0000000..b4a6161
--- /dev/null
+++ b/npm/bin/qsp.js
@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// Thin launcher: runs the Python `quicksilverpro` CLI pinned to this package's
+// version via uv (uvx), falling back to pipx. No network calls of its own.
+"use strict";
+const { spawnSync } = require("node:child_process");
+const { version } = require("../package.json");
+
+const args = process.argv.slice(2);
+const spec = `quicksilverpro==${version}`;
+
+function has(cmd) {
+  const probe = spawnSync(process.platform === "win32" ? "where" : "which", [cmd], { stdio: "ignore" });
+  return probe.status === 0;
+}
+
+function run(cmd, cmdArgs) {
+  const res = spawnSync(cmd, cmdArgs, { stdio: "inherit", env: process.env });
+  if (res.error) {
+    console.error(`quicksilverpro: failed to start ${cmd}: ${res.error.message}`);
+    process.exit(1);
+  }
+  process.exit(res.status === null ? 1 : res.status);
+}
+
+if (has("uvx")) {
+  run("uvx", ["--from", spec, "qsp", ...args]);
+} else if (has("pipx")) {
+  run("pipx", ["run", "--spec", spec, "qsp", ...args]);
+} else {
+  console.error(
+    [
+      "quicksilverpro needs uv (recommended) or pipx to run the Python CLI.",
+      "",
+      "Install uv (one line), then re-run this command:",
+      process.platform === "win32"
+        ? '  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"'
+        : "  curl -LsSf https://astral.sh/uv/install.sh | sh",
+      "",
+      "Or install directly: pip install quicksilverpro   (or: brew install machinefi/qspro/qspro)",
+    ].join("\n"),
+  );
+  process.exit(127);
+}
diff --git a/npm/package.json b/npm/package.json
new file mode 100644
index 0000000..3a67242
--- /dev/null
+++ b/npm/package.json
@@ -0,0 +1,17 @@
+{
+  "name": "quicksilverpro",
+  "version": "0.5.1",
+  "description": "QuickSilver Pro CLI (qsp): one API for frontier models, and cloud dev boxes your agents can run. Thin npm launcher for the Python CLI.",
+  "bin": {
+    "quicksilverpro": "bin/qsp.js",
+    "qsp": "bin/qsp.js"
+  },
+  "files": ["bin/", "README.md"],
+  "engines": { "node": ">=18" },
+  "keywords": ["quicksilver", "llm", "openai-compatible", "claude-code", "codex", "mcp", "dev-box", "agents", "cli"],
+  "homepage": "https://quicksilverpro.io/docs/machines/cli/",
+  "repository": { "type": "git", "url": "git+https://github.com/machinefi/qspro-cli.git", "directory": "npm" },
+  "bugs": "https://github.com/machinefi/qspro-cli/issues",
+  "license": "MIT",
+  "author": "MachineFi Inc."
+}