diff --git a/README.md b/README.md
index b32dbac49..95252f678 100644
--- a/README.md
+++ b/README.md
@@ -41,21 +41,21 @@ Model note: while any model is supported, I strongly recommend **Anthropic Pro/M
 
 Do **not** download prebuilt binaries. Run from source.
 
-Prefer **Bun**. `pnpm` is also supported (see https://docs.clawd.bot/getting-started).
+Prefer `pnpm` for builds from source. Bun is optional for running TypeScript directly.
 
 ```bash
 # Clone this repo
 git clone https://github.com/clawdbot/clawdbot.git
 cd clawdbot
 
-bun install
-bun run ui:install
-bun run ui:build
-bun run build
-bun run clawdbot onboard
+pnpm install
+pnpm ui:install
+pnpm ui:build
+pnpm build
+pnpm clawdbot onboard
 ```
 
-Note: `bun run clawdbot ...` runs TypeScript directly. `bun run build` produces `dist/` for running via Node / the packaged `clawdbot` binary.
+Note: `pnpm clawdbot ...` runs TypeScript directly (via `tsx`). `pnpm build` produces `dist/` for running via Node / the packaged `clawdbot` binary.
 
 ## Quick start (TL;DR)
 
@@ -64,23 +64,23 @@ Runtime: **Node ≥22**.
 Full beginner guide (auth, pairing, providers): https://docs.clawd.bot/getting-started
 
 ```bash
-bun run clawdbot onboard
+pnpm clawdbot onboard
 
-bun run clawdbot gateway --port 18789 --verbose
+pnpm clawdbot gateway --port 18789 --verbose
 
 # Dev loop (auto-reload on TS changes)
-bun run gateway:watch
+pnpm gateway:watch
 
 # Send a message
-bun run clawdbot send --to +1234567890 --message "Hello from Clawdbot"
+pnpm clawdbot send --to +1234567890 --message "Hello from Clawdbot"
 
 # Talk to the assistant (optionally deliver back to WhatsApp/Telegram/Slack/Discord)
-bun run clawdbot agent --message "Ship checklist" --thinking high
+pnpm clawdbot agent --message "Ship checklist" --thinking high
 ```
 
 Upgrading? https://docs.clawd.bot/updating (and run `clawdbot doctor`).
 
-If you run from source, prefer `bun run clawdbot …` or `pnpm clawdbot …` (not global `clawdbot`).
+If you run from source, prefer `pnpm clawdbot …` (not global `clawdbot`).
 
 ## Security defaults (DM access)
 
diff --git a/docs/automation/webhook.md b/docs/automation/webhook.md
index 2183f8a7c..b235dd824 100644
--- a/docs/automation/webhook.md
+++ b/docs/automation/webhook.md
@@ -91,7 +91,7 @@ Mapping options (summary):
 - `hooks.mappings` lets you define `match`, `action`, and templates in config.
 - `hooks.transformsDir` + `transform.module` loads a JS/TS module for custom logic.
 - Use `match.source` to keep a generic ingest endpoint (payload-driven routing).
-- TS transforms require a TS loader (e.g. `bun`) or precompiled `.js` at runtime.
+- TS transforms require a TS loader (e.g. `bun` or `tsx`) or precompiled `.js` at runtime.
 - `clawdbot hooks gmail setup` writes `hooks.gmail` config for `clawdbot hooks gmail run`.
 See [`docs/gmail-pubsub.md`](https://docs.clawd.bot/automation/gmail-pubsub) for the full Gmail watch flow.
 
diff --git a/docs/install/bun.md b/docs/install/bun.md
index e1a4803cd..08d844f12 100644
--- a/docs/install/bun.md
+++ b/docs/install/bun.md
@@ -7,12 +7,12 @@ read_when:
 
 # Bun
 
-Goal: run this repo with **Bun** (preferred) without losing pnpm patch behavior.
+Goal: run this repo with **Bun** (optional) without losing pnpm patch behavior.
 
 ## Status
 
-- Bun is the preferred local runtime for running TypeScript directly (`bun run …`, `bun --watch …`).
-- `pnpm` is still fully supported (and used by some docs tooling).
+- Bun is an optional local runtime for running TypeScript directly (`bun run …`, `bun --watch …`).
+- `pnpm` is the default for builds and remains fully supported (and used by some docs tooling).
 - Bun cannot use `pnpm-lock.yaml` and will ignore it.
 
 ## Install
diff --git a/docs/reference/test.md b/docs/reference/test.md
index c04b7b62e..6cfdea87a 100644
--- a/docs/reference/test.md
+++ b/docs/reference/test.md
@@ -14,7 +14,7 @@ read_when:
 Script: [`scripts/bench-model.ts`](https://github.com/clawdbot/clawdbot/blob/main/scripts/bench-model.ts)
 
 Usage:
-- `source ~/.profile && bun scripts/bench-model.ts --runs 10`
+- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
 - Optional env: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
 - Default prompt: “Reply with a single word: ok. No punctuation or extra text.”
 
diff --git a/docs/start/getting-started.md b/docs/start/getting-started.md
index e78edca2e..27f7e12bf 100644
--- a/docs/start/getting-started.md
+++ b/docs/start/getting-started.md
@@ -22,7 +22,7 @@ If you want the deeper reference pages, jump to: [Wizard](/wizard), [Setup](/set
 ## 0) Prereqs
 
 - Node `>=22`
-- `bun` (preferred) or `pnpm`
+- `pnpm` (recommended) or `bun` (optional)
 - Git
 
 macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough.
@@ -32,13 +32,13 @@ macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway
 ```bash
 git clone https://github.com/clawdbot/clawdbot.git
 cd clawdbot
-bun install
+pnpm install
 ```
 
-Note: `pnpm` is also supported:
+Note: Bun is optional if you prefer running TypeScript directly:
 
 ```bash
-pnpm install
+bun install
 ```
 
 ## 2) Build the Control UI (recommended)
@@ -46,9 +46,9 @@ pnpm install
 The Gateway serves the browser dashboard (Control UI) when assets exist.
 
 ```bash
-bun run ui:install
-bun run ui:build
-bun run build
+pnpm ui:install
+pnpm ui:build
+pnpm build
 ```
 
 If you skip UI build, the gateway still works — you just won’t get the dashboard.
@@ -56,7 +56,7 @@ If you skip UI build, the gateway still works — you just won’t get the dashb
 ## 3) Run the onboarding wizard
 
 ```bash
-bun run clawdbot onboard
+pnpm clawdbot onboard
 ```
 
 What you’ll choose:
@@ -98,7 +98,7 @@ https://github.com/oven-sh/bun/issues/5951
 ### WhatsApp (QR login)
 
 ```bash
-bun run clawdbot login
+pnpm clawdbot login
 ```
 
 Scan via WhatsApp → Settings → Linked Devices.
@@ -118,8 +118,8 @@ Default posture: unknown DMs get a short code and messages are not processed unt
 Approve:
 
 ```bash
-bun run clawdbot pairing list --provider telegram
-bun run clawdbot pairing approve --provider telegram <CODE>
+pnpm clawdbot pairing list --provider telegram
+pnpm clawdbot pairing approve --provider telegram <CODE>
 ```
 
 Pairing doc: [Pairing](/pairing)
@@ -129,8 +129,8 @@ Pairing doc: [Pairing](/pairing)
 In a new terminal:
 
 ```bash
-bun run clawdbot health
-bun run clawdbot send --to +15555550123 --message "Hello from Clawdbot"
+pnpm clawdbot health
+pnpm clawdbot send --to +15555550123 --message "Hello from Clawdbot"
 ```
 
 If `health` shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it.
diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index e01a8d1d8..be656b7ad 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -71,21 +71,21 @@ Paste the token into the UI settings (sent as `connect.params.auth.token`).
 The Gateway serves static files from `dist/control-ui`. Build them with:
 
 ```bash
-bun run ui:install
-bun run ui:build
+pnpm ui:install
+pnpm ui:build
 ```
 
 Optional absolute base (when you want fixed asset URLs):
 
 ```bash
-CLAWDBOT_CONTROL_UI_BASE_PATH=/clawdbot/ bun run ui:build
+CLAWDBOT_CONTROL_UI_BASE_PATH=/clawdbot/ pnpm ui:build
 ```
 
 For local development (separate dev server):
 
 ```bash
-bun run ui:install
-bun run ui:dev
+pnpm ui:install
+pnpm ui:dev
 ```
 
 Then point the UI at your Gateway WS URL (e.g. `ws://127.0.0.1:18789`).
diff --git a/docs/web/index.md b/docs/web/index.md
index 5f678a24d..89eed6e68 100644
--- a/docs/web/index.md
+++ b/docs/web/index.md
@@ -101,6 +101,6 @@ Open:
 The Gateway serves static files from `dist/control-ui`. Build them with:
 
 ```bash
-bun run ui:install
-bun run ui:build
+pnpm ui:install
+pnpm ui:build
 ```
diff --git a/package.json b/package.json
index 8dd1f0b7c..e9075e7ad 100644
--- a/package.json
+++ b/package.json
@@ -44,20 +44,20 @@
     "LICENSE"
   ],
   "scripts": {
-    "dev": "bun src/entry.ts",
+    "dev": "tsx src/entry.ts",
     "postinstall": "node scripts/postinstall.js",
-    "docs:list": "bun scripts/docs-list.ts",
+    "docs:list": "tsx scripts/docs-list.ts",
     "docs:dev": "cd docs && mint dev",
     "docs:build": "cd docs && pnpm dlx mint broken-links",
-    "build": "tsc -p tsconfig.json && bun scripts/canvas-a2ui-copy.ts",
-    "release:check": "bun scripts/release-check.ts",
+    "build": "tsc -p tsconfig.json && tsx scripts/canvas-a2ui-copy.ts",
+    "release:check": "tsx scripts/release-check.ts",
     "ui:install": "node scripts/ui.js install",
     "ui:dev": "node scripts/ui.js dev",
     "ui:build": "node scripts/ui.js build",
-    "start": "bun src/entry.ts",
-    "clawdbot": "bun src/entry.ts",
-    "gateway:watch": "bun --watch src/entry.ts gateway --force",
-    "clawdbot:rpc": "bun src/entry.ts agent --mode rpc --json",
+    "start": "tsx src/entry.ts",
+    "clawdbot": "tsx src/entry.ts",
+    "gateway:watch": "tsx watch src/entry.ts -- gateway --force",
+    "clawdbot:rpc": "tsx src/entry.ts agent --mode rpc --json",
     "lint": "biome check src test && oxlint --type-aware src test --ignore-pattern src/canvas-host/a2ui/a2ui.bundle.js",
     "lint:swift": "swiftlint lint --config .swiftlint.yml && (cd apps/ios && swiftlint lint --config .swiftlint.yml)",
     "lint:fix": "biome check --write --unsafe src && biome format --write src",
@@ -65,12 +65,12 @@
     "format:swift": "swiftformat --lint --config .swiftformat apps/macos/Sources apps/ios/Sources apps/shared/ClawdbotKit/Sources",
     "format:fix": "biome format src --write",
     "test": "vitest",
-    "test:force": "bun scripts/test-force.ts",
+    "test:force": "tsx scripts/test-force.ts",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "test:docker:qr": "bash scripts/e2e/qr-import-docker.sh",
-    "protocol:gen": "bun scripts/protocol-gen.ts",
-    "protocol:gen:swift": "bun scripts/protocol-gen-swift.ts",
+    "protocol:gen": "tsx scripts/protocol-gen.ts",
+    "protocol:gen:swift": "tsx scripts/protocol-gen-swift.ts",
     "protocol:check": "pnpm protocol:gen && pnpm protocol:gen:swift && git diff --exit-code -- dist/protocol.schema.json apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift",
     "canvas:a2ui:bundle": "bash scripts/bundle-a2ui.sh"
   },
@@ -142,6 +142,7 @@
     "quicktype-core": "^23.2.6",
     "rolldown": "1.0.0-beta.58",
     "signal-utils": "^0.21.1",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16",
     "wireit": "^0.14.12"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index cdaa899e7..f8e1e95a4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -197,6 +197,9 @@ importers:
       signal-utils:
         specifier: ^0.21.1
         version: 0.21.1(signal-polyfill@0.2.2)
+      tsx:
+        specifier: ^4.21.0
+        version: 4.21.0
       typescript:
         specifier: ^5.9.3
         version: 5.9.3
@@ -4754,7 +4757,6 @@ snapshots:
   get-tsconfig@4.13.0:
     dependencies:
       resolve-pkg-maps: 1.0.0
-    optional: true
 
   glob-parent@5.1.2:
     dependencies:
@@ -5515,8 +5517,7 @@ snapshots:
 
   require-from-string@2.0.2: {}
 
-  resolve-pkg-maps@1.0.0:
-    optional: true
+  resolve-pkg-maps@1.0.0: {}
 
   retry@0.12.0: {}
 
@@ -5838,7 +5839,6 @@ snapshots:
       get-tsconfig: 4.13.0
     optionalDependencies:
       fsevents: 2.3.3
-    optional: true
 
   type-is@2.0.1:
     dependencies: