@openclaw/babelfish

Babelfish 🐟 — Plugins, translated

Babelfish imports plugins from Claude Code, Codex, and Hermes Agent into OpenClaw. It translates compatible tools, skills, commands, hooks, middleware, and MCP surfaces into native OpenClaw contracts, while reporting source behavior that has no safe equivalent.

Install

Install the published OpenClaw plugin:

openclaw plugins install npm:@openclaw/babelfish

Restart OpenClaw after installation. Babelfish requires Node.js 22.19 or newer.

Quick start

Import a plugin from its Git repository, then inspect what Babelfish found:

openclaw babelfish install codex https://github.com/Kotlin/kotlin-agent-skills.git
openclaw babelfish list codex

Restart OpenClaw again to load the generated contracts and skills. Supported app identifiers are claude-code, codex, and hermes.

What gets imported

Babelfish preserves source names when they are unique and qualifies collisions with the plugin name. Install and uninstall operations regenerate the OpenClaw plugin manifest, tool registry, and imported skill directories.

Installing an already installed name requires --force; a rejected duplicate leaves the existing plugin intact and creates no staging directory.

Source contribution	OpenClaw behavior
Agent and MCP tools	Native tools that retain the source JSON schema. MCP inspection follows at most 50 tool pages within one request-timeout budget and rejects repeated cursors.
Skills and support files	Native OpenClaw skills with referenced files intact; Markdown frontmatter supports LF and Windows CRLF. Generated command, agent, and output-style descriptions support literal and folded YAML blocks, header comments, one-digit indentation indicators, and clip/strip/keep chomping. Copied skill bodies and assets remain intact. In-root directory names such as ..skills are supported.
Prompt and terminal commands	User-invoked skills or top-level CLI commands when the source format supports them. Hermes MCP command tools accept optional args: omitted arguments, {}, or an empty args string pass ""; explicit text is preserved.
Compatible hooks	Matching lifecycle, prompt, tool, compaction, and subagent hooks. Discovery permits 50 unique hook files and eight nested directories. Command-hook stdin is capped at 1 MiB; oversized decision events fail closed. String commands use a login shell; args or a command array spawn without a shell. Single-quoted names inside $(...) and backticks are inserted. Windows copies those inserted values without a POSIX apostrophe escape.
Compatible middleware	Matching prompt-build and tool-result middleware
Hermes availability	An absent or empty install needs no Python for discovery or hooks; installed or unknown providers still require it, and failed pre-tool guards prevent execution
Session-start context	Turn preparation waits for an in-flight session start. A failed start warns once instead of poisoning later turns; successful start context is consumed once. Concurrent prepares cannot bypass a pending start or remove a newer one.
Session monitors	Always-on Claude monitors keep at most 50 stdout lines and 1 MiB of queued context per session. A line over 1 MiB stops that monitor; consumed output does not count against future turns.
Hook command expansion	An unresolved variable blocks PreToolUse, UserPromptSubmit, and Stop decisions while preserving earlier results and running later hooks. Observer expansion failures warn and continue. The POSIX shell expands bare and double-quoted references; Babelfish inserts single-quoted and escaped references as literal values, preserving installed deny guards. Windows retains native cmd.exe expansion semantics. Execution-error handling is unchanged.
Stop hook decisions	On upgrade, installed Claude Code and Codex Stop hooks with continue: false finish the turn rather than request revision. This takes precedence over a block on the same hook only; a separate blocking hook still requests revision in either order. Pre-tool and prompt blocking is unchanged.
Unsupported behavior	Recorded during generation and reported at Gateway startup

Support differs by source app and surface. See the compatibility reference for the full matrix, source-specific behavior, configuration, and example plugins.

The compatibility reference ships in the npm package. Release validation tests the actual tarball in a fresh production-only consumer; see the release procedure.

Command-hook results, including blocking exit decisions, are retained when a hook exits without reading all stdin.

Trust and lifecycle

Installing a plugin executes code from its repository while Babelfish inspects MCP tools and later runs imported hooks or tools. Review the source before installing it. String hook commands are full shell execution. Hooks that declare args or a command array spawn the listed executable directly.

Babelfish does not expose install or uninstall as agent tools. The read-only babelfish_plugins_list agent tool reports installed plugins and detected surfaces. Restart OpenClaw after installing, updating, or removing an imported plugin because OpenClaw loads plugin metadata and tool contracts at process startup.

Commands

Command	Purpose
openclaw babelfish list [app]	List installed plugins and detected surfaces
openclaw babelfish install <app> <git-url> [--name <name>] [--force] [--clone-timeout-ms <ms>]	Install a source plugin from Git. Clone waits 120 seconds by default; pass --clone-timeout-ms or set OPENCLAW_BABELFISH_CLONE_TIMEOUT_MS for a slower healthy remote
openclaw babelfish uninstall <app> <name>	Remove an imported plugin
babelfish mcp	Start the optional Hermes-only stdio MCP server; background tasks allow eight isolated processes, including children still exiting after completion or stop

The standalone MCP server is a compatibility fallback for MCP clients; native OpenClaw loading remains the recommended path. See Manual MCP server for setup and limitations. Task results become available when the helper returns; its concurrency slot remains occupied until the child exits.

Development

Development requires Node.js 22.19 or newer, npm, Git, and python3 for the Hermes bridge tests.

npm ci
npm run check
npm run pack:check

The test suite covers source-runtime tools, commands, skills, hook translation, bundle discovery, transactional install and uninstall, and the optional MCP server. npm run test:low-memory runs the full gate at 1 GiB, runtime and end-to-end flows at 512 MiB, and install/list/uninstall plus MCP stdio at 256 MiB.

See CONTRIBUTING.md for focused test commands and pull request guidance, and report vulnerabilities according to SECURITY.md.

License

Babelfish is available under the MIT License.