Skip to content

Self-improving AI Employees for everyone

docs: finish the bun-only sweep across node cards, skills and references

trohitgc11ef17dc7d7
diff --git a/CLAUDE.md b/CLAUDE.md
index 670ac346..027309ba 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -284,7 +284,7 @@ server/nodes/code/ # Executor plugins (javascript_executor, types
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check: `runtime: "bun"`, `runtime_version`, and still `node_version` (the Node API level bun reports) |
-| `/execute` | POST | Execute JS/TS code with input_data and timeout |
+| `/execute` | POST | Execute JS/TS code with input_data and timeout (`language: "typescript"` is type-stripped by `Bun.Transpiler` first, then both run in a `node:vm` context) |
| `/packages/install` | POST | Install npm-registry packages into user-packages via `bun add` (run through `process.execPath`, i.e. the sidecar's own bun) |
| `/packages` | GET | List installed packages from the user-packages dir's `package.json` |
@@ -443,7 +443,7 @@ locked by `server/tests/test_output_contract.py`.
**Always use the existing design and theme systems.** Tribal styling reintroduced anywhere defeats the migration. The following rules are non-negotiable for any new or edited frontend file:
-1. **Compose shadcn primitives** from [client/src/components/ui/](./client/src/components/ui/) — `Button`, `Badge`, `Alert`, `AlertDialog`, `Dialog`, `DropdownMenu`, `Select`, `Progress`, `Tooltip`, `Tabs`, `Card`, `Input`, `Textarea`, `Switch`, `Checkbox`, `Slider`, `Label`, `Form`, `Collapsible`, `Accordion`, `Skeleton`, `Sonner`. **Do not hand-roll** modals, dropdowns, menus, toasts, dialogs, or buttons when a primitive exists. Add `npx shadcn@latest add <name>` if the primitive is missing.
+1. **Compose shadcn primitives** from [client/src/components/ui/](./client/src/components/ui/) — `Button`, `Badge`, `Alert`, `AlertDialog`, `Dialog`, `DropdownMenu`, `Select`, `Progress`, `Tooltip`, `Tabs`, `Card`, `Input`, `Textarea`, `Switch`, `Checkbox`, `Slider`, `Label`, `Form`, `Collapsible`, `Accordion`, `Skeleton`, `Sonner`. **Do not hand-roll** modals, dropdowns, menus, toasts, dialogs, or buttons when a primitive exists. Add `bun x shadcn@latest add <name>` if the primitive is missing.
2. **Action buttons → `<ActionButton intent="...">`** ([client/src/components/ui/action-button.tsx](./client/src/components/ui/action-button.tsx)). The `intent` prop is a semantic role (`run | stop | save | config | secret | tools`), never a palette color. Never re-introduce the `actionButtonStyle()` / hand-built colored buttons.
3. **Style with Tailwind classes**, not `style={{...}}`. Inline `style` is allowed only for genuinely dynamic values (React Flow `<Handle>` positioning, runtime-computed coordinates, dynamic per-definition `nodeColor` on canvas nodes).
4. **Use the token tier table** in [docs-internal/frontend_architecture.md](./docs-internal/frontend_architecture.md#tokens--theming):
@@ -807,7 +807,7 @@ See **[Scripts Reference](./docs-internal/SCRIPTS.md)** for full documentation.
✅ **Production Deployment**: `company deploy` provisions a login-gated VM via Terraform + cloud-init running `company serve` under systemd; the Docker Compose topology was removed (see [deployment_legacy.md](./docs-internal/deployment_legacy.md))
✅ **Authentication System**: n8n-style JWT authentication with HttpOnly cookies, single-owner and multi-user modes, rate-limited login. Note `AUTH_MODE=multi` authenticates but does NOT isolate data — see Known Limitations in [authentication.md](./docs-internal/authentication.md)
✅ **Cache System**: n8n-pattern cache with Redis (production) / SQLite (local dev) / Memory fallback hierarchy
-✅ **AI Thinking/Reasoning**: Extended thinking for Claude, Gemini 2.5/3, OpenAI GPT-5/o-series, Groq Qwen3 with output available in Input Data & Variables for downstream nodes
+✅ **AI Thinking/Reasoning**: Extended thinking for Claude, Gemini 2.5/3, OpenAI GPT-5/GPT-6/o-series, Groq Qwen3 with output available in Input Data & Variables for downstream nodes
✅ **Onboarding Service**: 4-step welcome wizard with shadcn UI, database persistence, skip/resume/replay support
✅ **Proxy System**: Residential proxy provider management with template-based URL formatting, auto-selection by health score, transparent proxy injection on httpRequest/httpScraper nodes via `useProxy: true`
✅ **Markdown Formatter**: GFM markdown to platform-native formatting (Telegram HTML, WhatsApp syntax, plain text) using markdown-it-py
diff --git a/cli/README.md b/cli/README.md
index 31e2be64..29c4ef1b 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -23,7 +23,7 @@ company --help # list commands
company stop # kill ports + orphans + temporal
```
-Or via the npm scripts (which now invoke the same Python CLI):
+Or via the package.json scripts (`bun run <script>`, which invoke the same Python CLI):
```sh
bun run stop
diff --git a/docs-internal/cli_services_integration.md b/docs-internal/cli_services_integration.md
index 8bfe45f1..4a6e8615 100644
--- a/docs-internal/cli_services_integration.md
+++ b/docs-internal/cli_services_integration.md
@@ -67,7 +67,7 @@ Follow the plugin-runtime pattern (references: `nodes/whatsapp/_runtime.py`,
|---------|---------------|-----------------|
| Spawning from a status refresh | a passive probe boots an optional daemon | Consult the supervisor (`is_running()`); demand signals own the starts |
| Adding plugin-daemon ports to `Config.all_ports` | the CLI would kill a backend-owned daemon during startup | The backend supervises them; the CLI carries no plugin knowledge |
-| Resolving `node_modules/.bin/<cli>` path | Breaks if not in PATH, tribal workaround | Install globally |
-| Using `npx <service-cli>` in `execSync` | Slow, may use wrong version, npx overhead | Install globally, call directly |
+| Spelling `node_modules/.bin/<cli>[.cmd]` by hand | Drifts per platform (bun writes `<name>.exe` + `<name>.bunx` on Windows, `<name>` elsewhere) | `core.js_runtime.shared_tree_bin(name)` after `add_package(spec)` |
+| Running the CLI through `bun x` / `npx` per call | Slow, unpinned version, no shared tree | `add_package("<pkg>@<version>")` once into the shared packages tree, then call the shim directly |
| Wrapping CLI in a JS script | Unnecessary indirection | Use CLI commands directly |
| Hardcoding port numbers in code or docs | drifts when ports change | Declare in `.env.template`; read via `core.env_defaults` |
diff --git a/docs-internal/errors.md b/docs-internal/errors.md
index 9c83bd5f..ddef7788 100644
--- a/docs-internal/errors.md
+++ b/docs-internal/errors.md
@@ -505,3 +505,11 @@ uv then downloads its 3.12 into `~/.local/share/uv`, the venvs are usable by the
**Root cause**: The `tar` first on PATH in a Git Bash shell is Git for Windows' GNU tar, which cannot read `.zip` and parses `D:\...` as `host:path`. The system bsdtar at `%SystemRoot%\System32\tar.exe` handles zip, tar.gz and tar.xz.
**Fix**: `desktop/scripts/_lib.ts::tarBinary()` prefers the System32 tar on Windows and always passes the archive as a path relative to the extraction directory so no argument carries a drive colon.
+
+## 23. `company: command not found` after `bun add -g`, or `bun pm ls -g` aborts with `InvalidNPMLockfile`
+
+**Symptom**: `bun add -g @zeenie-ai/opencompany` succeeds, but `company` is not found in the same shell; or `bun pm ls -g` prints `error: failed to migrate lockfile: InvalidNPMLockfile`.
+
+**Root cause**: bun puts global bin shims in `$(bun pm bin -g)` (`~/.bun/bin`, or `$BUN_INSTALL/bin`), which a shell opened before the bun installer ran does not have on PATH. Separately, bun keeps its global packages in a directory it chooses per platform and configuration (on Windows 1.4 it was the user profile, not `$BUN_INSTALL/install/global`), and a stray npm `package-lock.json` in that directory makes `bun pm ls -g` try to migrate it and fail.
+
+**Fix**: open a new shell, or `export PATH="$HOME/.bun/bin:$PATH"` (`$env:USERPROFILE\.bun\bin` on Windows). Nothing in OpenCompany depends on where the global package lives: `company provision` runs from the shim's own package root, `uninstall.sh` uses `bun remove -g` rather than listing, and the installers address the shim through `bun pm bin -g`. Delete the stray `package-lock.json` only if you know it is not yours.
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.md
index 670df6a7..40b010ee 100644
--- a/docs-internal/frontend_architecture.md
+++ b/docs-internal/frontend_architecture.md
@@ -603,7 +603,7 @@ The DIY widget registry (RHF + zod + a tester+rank dispatch) is modeled on n8n's
| [client/src/components/ui/alert-dialog.tsx](../client/src/components/ui/alert-dialog.tsx) | Confirmation / destructive-action modals. **Never hand-roll a `position: fixed; background: rgba(0,0,0,0.5)` backdrop** — use `<AlertDialog open onOpenChange>` with `AlertDialogHeader` / `AlertDialogDescription` / `AlertDialogFooter`. Focus trap, escape-to-close, and `role="alertdialog"` come from Radix. MiddleSection Clear Memory + Reset Skill dialogs are the canonical consumers (Wave 3 commit `61bf23c`). |
| [client/src/components/ui/sonner.tsx](../client/src/components/ui/sonner.tsx) | The `<Toaster />` mount — call `import { toast } from 'sonner'` directly at use sites; do not wrap. |
| [client/src/components/ui/Modal.tsx](../client/src/components/ui/Modal.tsx) | Composition primitive on top of shadcn `<Dialog>`. Owns the recurring "title bar with centered headerActions and a close button + size-constrained content panel" 8 panels share. Not an antd facade. For destructive confirmations prefer `AlertDialog` above. |
-| `client/src/components/ui/{button,input,select,switch,checkbox,form,…}.tsx` | shadcn-generated primitives. Add new ones via `npx shadcn@latest add <name>`. Don't re-implement what the registry ships. |
+| `client/src/components/ui/{button,input,select,switch,checkbox,form,…}.tsx` | shadcn-generated primitives. Add new ones via `bun x shadcn@latest add <name>`. Don't re-implement what the registry ships. |
## Theme + canvas chrome
diff --git a/docs-internal/node-logic-flows/specialized_agents/claude_code_agent.md b/docs-internal/node-logic-flows/specialized_agents/claude_code_agent.md
index f6b81ac1..19861cb5 100644
--- a/docs-internal/node-logic-flows/specialized_agents/claude_code_agent.md
+++ b/docs-internal/node-logic-flows/specialized_agents/claude_code_agent.md
@@ -159,7 +159,7 @@ flowchart TD
## External Dependencies
-- **Binaries**: `@anthropic-ai/claude-code`, OpenCompany-managed — auto-installed on first use into the shared npm tree at `<DATA_DIR>/packages/` (binary at `<DATA_DIR>/packages/node_modules/.bin/claude[.cmd]`); requires `npm` on PATH.
+- **Binaries**: `@anthropic-ai/claude-code`, OpenCompany-managed — auto-installed on first use into the shared packages tree at `<DATA_DIR>/packages/` with `bun add --trust` via `core.js_runtime.add_package` (bin shim at `<DATA_DIR>/packages/node_modules/.bin/claude[.exe]`, executed on the bun runtime); requires bun (`OPENCOMPANY_BUN_BIN` or PATH), never Node or npm.
- **Python packages**: standard library + the `services/cli_agent/` framework
(FastMCP bridge, session pool).
- **Credentials**: Claude Code handles its own authentication via
diff --git a/docs-internal/node-logic-flows/web_automation/browser.md b/docs-internal/node-logic-flows/web_automation/browser.md
index 93232e5e..2c379140 100644
--- a/docs-internal/node-logic-flows/web_automation/browser.md
+++ b/docs-internal/node-logic-flows/web_automation/browser.md
@@ -14,9 +14,11 @@
Interactive browser automation via the `agent-browser` CLI. The binary is a
OpenCompany-managed local install resolved by
[`nodes/browser/_install.py::agent_browser_binary_path`](../../../server/nodes/browser/_install.py)
-(installed via `npm install agent-browser --prefix <package_dir>` on first use,
-same pattern as Claude Code's project-local CLI — NOT a workspace `package.json`
-dependency and NOT invoked through `npx`). Exposes 14 discrete operations (navigate,
+(installed on first use with `bun add --trust` into the shared
+`<DATA_DIR>/packages/` tree via `core.js_runtime.add_package`, the same pattern
+as Claude Code's project-local CLI — NOT a workspace `package.json` dependency
+and NOT invoked through `bun x`; the shim runs on the bun runtime). Exposes 14
+discrete operations (navigate,
click, type, fill, screenshot, snapshot, get_text, get_html, eval, wait, scroll,
select, console, errors) plus a `batch` meta-op. The preferred workflow for an
AI agent is `navigate` -> `snapshot` -> `click`/`fill` using the stable `@eN`
@@ -147,7 +149,7 @@ flowchart TD
## Decision Logic
- **Service missing**: `get_browser_service()` returns `None` when the
- agent-browser binary cannot be resolved (Node toolchain / `npm` unavailable)
+ agent-browser binary cannot be resolved (bun unavailable, or the install failed)
-> `RuntimeError("agent-browser not installed...")` -> error envelope.
- **Session resolution**: empty `session` -> `opencompany_<execution_id>` via the
typed `ctx.execution_id` accessor (handles present-but-None on the agent
@@ -199,9 +201,10 @@ flowchart TD
## External Dependencies
- **Credentials**: none.
-- **Services**: `BrowserService` singleton; `npm` on PATH (for first-use
- install); `agent-browser` installed under `<package_dir("browser")>/npm/`
- by `nodes/browser/_install.py` (OpenCompany-managed, not a workspace dep).
+- **Services**: `BrowserService` singleton; bun (`OPENCOMPANY_BUN_BIN` or PATH)
+ for the first-use install and as the shim's runtime; `agent-browser`
+ installed into the shared `<DATA_DIR>/packages/` tree by
+ `nodes/browser/_install.py` (OpenCompany-managed, not a workspace dep).
- **Python packages**: `psutil` (via `kill_tree` for process-tree kill).
- **Environment variables**: `BROWSER_MAX_INSTANCES` (concurrent session cap,
default 3), `BROWSER_IDLE_TIMEOUT_MS` (daemon idle auto-shutdown in ms,
diff --git a/docs-internal/release_build_pipeline.md b/docs-internal/release_build_pipeline.md
index 56fc1b0a..efdf85cd 100644
--- a/docs-internal/release_build_pipeline.md
+++ b/docs-internal/release_build_pipeline.md
@@ -153,7 +153,7 @@ The tarball still excludes `__pycache__/` per `package.json` `files` (cross-Pyth
### 4b. Temporal binary fetch + DATA_DIR parity
-- Step `[6/6]` runs `uv run python -m services.temporal._install`, which pooch-downloads the official `temporal` CLI into `<DATA_DIR>/packages/temporal/` (= `~/.opencompany/packages/temporal/` by default). Pre-fetching at build time turns the ~114 MB download into a sub-second cache hit on first `company start`. The download uses an explicit `HTTPDownloader(timeout=300)` (per-socket-read timeout — slow links can finish; pooch's 30 s default aborted them). Fatality differs by entry point: `company build` keeps the step **fatal** (locked by `test_temporal_install_is_fatal_on_failure`), while npm postinstall (`scripts/install.js`) wraps it in a **non-fatal** try/catch because `TemporalServerRuntime._pre_spawn()` re-downloads lazily on first `company start`. The cache survives `company clean` (`packages` ∈ `_OPENCOMPANY_KEEP`), so clean+build cycles don't re-download.
+- Step `[6/6]` runs `uv run python -m services.temporal._install`, which pooch-downloads the official `temporal` CLI into `<DATA_DIR>/packages/temporal/` (= `~/.opencompany/packages/temporal/` by default). Pre-fetching at build time turns the ~114 MB download into a sub-second cache hit on first `company start`. The download uses an explicit `HTTPDownloader(timeout=300)` (per-socket-read timeout — slow links can finish; pooch's 30 s default aborted them). Fatality differs by entry point: `company build` keeps the step **fatal** (locked by `test_temporal_install_is_fatal_on_failure`), while the provisioning script (`scripts/install.js`, run by `company provision`) wraps it in a **non-fatal** try/catch because `TemporalServerRuntime._pre_spawn()` re-downloads lazily on first `company start`. The cache survives `company clean` (`packages` ∈ `_OPENCOMPANY_KEEP`), so clean+build cycles don't re-download.
- **`company build` layers `.env.dev` first.** `build_command()` calls `cli.config.load_dev_overrides(root)` before the install steps, so the build's `DATA_DIR` matches what the runtime sees. Without it, a repo checkout's `company build` read `DATA_DIR=~/.opencompany` from `.env.template` and installed Temporal under user home, but `company dev` then read `DATA_DIR=.opencompany` from `.env.dev` and re-downloaded into `<repo>/.opencompany/` — a redundant ~114 MB fetch on every fresh clone.
- **Safe for global installs.** `.env.dev` is git-committed for contributors but is NOT in the `files` list, so an installed (`bun add -g`) copy has no `.env.dev` — `load_dev_overrides` is a no-op and everything falls through to the `.env.template` default (`DATA_DIR=~/.opencompany`), matching `company start` / `company daemon`.
diff --git a/docs-internal/theme_system.md b/docs-internal/theme_system.md
index 77c842bd..709b13d1 100644
--- a/docs-internal/theme_system.md
+++ b/docs-internal/theme_system.md
@@ -482,7 +482,7 @@ cd client && bun run typecheck && bun run build
Touched components should pass lint:
```bash
-cd client && npx eslint <files>
+cd client && bun x eslint <files>
```
## File index
diff --git a/server/skills/coding_agent/javascript-skill/SKILL.md b/server/skills/coding_agent/javascript-skill/SKILL.md
index 54162e3e..93307403 100644
--- a/server/skills/coding_agent/javascript-skill/SKILL.md
+++ b/server/skills/coding_agent/javascript-skill/SKILL.md
@@ -1,6 +1,6 @@
---
name: javascript-skill
-description: Execute JavaScript code for calculations, data processing, and JSON manipulation. Full ES6+ support with Node.js runtime.
+description: Execute JavaScript code for calculations, data processing, and JSON manipulation. Full ES2022+ support on the bun runtime (Node-compatible APIs).
allowed-tools: "javascript_executor"
metadata:
author: opencompany
@@ -192,4 +192,4 @@ const obj = Object.fromEntries(arr.map(x => [x.id, x.name]));
## Setup Requirements
1. Connect the **JavaScript Executor** node to Zeenie's `input-tools` handle
-2. Node.js must be installed on the server
+2. bun must be available to the backend (the desktop app bundles it; the terminal install requires it)
diff --git a/server/skills/vercel/vercel-skill/SKILL.md b/server/skills/vercel/vercel-skill/SKILL.md
index 48e02d56..dcbed24b 100644
--- a/server/skills/vercel/vercel-skill/SKILL.md
+++ b/server/skills/vercel/vercel-skill/SKILL.md
@@ -161,7 +161,7 @@ Two independent paths (either is enough), configured in the
Credentials Modal → Vercel:
1. **Login with Vercel** — browser device flow driven through the
- CLI. The CLI is auto-installed via npm on first use and keeps its
+ CLI. The CLI is auto-installed with bun on first use and keeps its
auth state in a OpenCompany-owned config directory.
2. **Access token** — paste a token from
[vercel.com/account/tokens](https://vercel.com/account/tokens).