stdio-to-ws

library0.2.0jsnpmunverified

Bridge stdio processes to WebSocket connections. Current version is 0.2.0, with an active development cadence. It allows spawning a child process and piping its stdin/stdout to WebSocket clients, supporting line-based or raw framing. Key differentiators include built-in framing modes (line for NDJSON, raw with Content-Length stripping) and zero-config npx usage. Ideal for exposing CLI tools or AI agent protocols (e.g., Gemini CLI with ACP) over WebSocket without manual socket programming.

devops

npm install stdio-to-ws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · STDIO-TO-WS

stdio-to-ws

devopsjavascriptv0.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

startServer

✓ import { startServer } from 'stdio-to-ws'

✗ const { startServer } = require('stdio-to-ws')

Package is ESM-only (Node >=18). CommonJS require() will fail with ERR_REQUIRE_ESM.

StdioToWsServer

✓ import { StdioToWsServer } from 'stdio-to-ws'

TypeScript types are included; both named exports are available.

stdio-to-ws CLI

✓ npx stdio-to-ws [options] \"command\"

✗ stdio-to-ws [options] command

The package is designed primarily as a CLI tool. The CLI entry is 'stdio-to-ws' in npx or after installing globally.

Creates a WebSocket server that spawns a child process and bridges its stdio to connected clients using line framing.

import { startServer } from 'stdio-to-ws'; const server = startServer({ command: 'node -e "setInterval(() => console.log(\"ping\"), 1000)"', port: 3000, framing: 'line', }); console.log('WebSocket server running on ws://localhost:3000'); server.on('connection', (ws) => { ws.on('message', (data) => console.log('Received from client:', data.toString())); });

Debug

Known issues

breakingPackage is ESM-only. Requires Node.js >=18 and cannot be used with CommonJS require().

fix

Use import syntax or migrate project to ESM. For Node.js <18, use an older version or a different tool.

affects: >=0.2.0

gotchaLine framing mode assumes each stdout line is a complete message; if a process outputs partial lines (e.g., unbuffered), messages may be split or combined.

fix

Use raw framing for binary or non-line-oriented output, or configure the child process to flush lines (e.g., stdio: 'pipe' in Node child_process).

affects: >=0.0.0

deprecatedNo deprecated features as of 0.2.0.

affects: none

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module

Trying to import the package with require() in a CommonJS file.

fix

Use import('stdio-to-ws') dynamic import or convert file to ESM.

Command failed: ... [Error: spawn ... ENOENT]

The command string is not found or not executable in the system PATH.

fix

Provide the full path to the command or ensure it's available in the environment where the server runs.

WebSocket connection closed unexpectedly

Child process exited or stdin ended, causing the bridge to close the WebSocket.

fix

Handle the 'close' event on the server and optionally restart the process using the 'command' option.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/marimo-team/stdio-to-ws ↗

packagestdio-to-ws ↗

homepagehttps://github.com/marimo-team/stdio-to-ws#readme ↗