Toward First‑Class Extensibility in Zed: A Rhai‑Based Proposal

[oscarvarto]

Toward First‑Class Extensibility in Zed: A Rhai‑Based Proposal

Summary

Zed’s extensions are safe, fast, and portable via Rust→WASM (WASI + WIT). That model protects performance and reliability, but it makes “live, programmable” customization (the Emacs/Lisp experience) harder: most logic lives in compiled Rust, and today’s extension hooks focus on LSP/DAP rather than general editor events. This document:

• States the need for a small, dynamic scripting layer alongside JSONC config.
• Argues for Rhai (a Rust‑native embeddable language) as a practical first candidate within Zed’s WASM architecture.
• Compares Rhai to Lua and other options.
• Outlines an implementation that fits Zed’s current codebase and docs, and describes incremental API additions to unlock Emacs‑like extensibility, customizability, and introspection.

The Problem

• Great performance, limited “hackability”: Zed’s Rust/WASM extensions are fast and secure but require a compile step. This slows the “tweak → eval → iterate” loop that makes Emacs compelling.
• Hooks skew toward tooling: The Extension trait primarily covers LSP/DAP/context servers/slash commands. There’s no stable, general set of editor events for scripts to observe and react to (buffer open/save/selection changes, etc.).
• Config is data only: Zed supports JSONC for settings, which is right for data, but many users need light logic (e.g., conditionals, commands/macros, contributions) without shipping a full Rust extension.
• Community demand: There are active asks for a dynamic/config language and richer extension hooks:
  • add lua as an optional config language (add lua as an optional config language #13491)
  • Command palette/projects/text buffer extension API (Command palette/projects/text buffer extension API #18043)
  • Allow registering custom actions (Discussion Allow registering custom actions from extensions #39554)
  • Expose Workspace to the Extension (Expose Workspace to the Extension #20831); Webview via Extensions (Webview via Extensions #21208)
  • Support external formatters (Extension API: Support for external formatters other binaries #31904)
  • Improve agility by offloading to extensions and scripting (Discussion Improve agility to agent support by offloading it to extensions and scripting #38249)
  • Proposal for Lisp as the Extension Mechanism (Discussion Proposal for Lisp as the Extension Mechanism #14539)

Today’s Extension Model (Pointers)

• Core API
  • crates/extension_api/src/extension_api.rs: Extension trait and host functions (e.g., run_slash_command, complete_slash_command_argument, language_server_command).
  • crates/extension_api/wit/since_v0.6.0/extension.wit: WIT definitions for the extension world; especially resource worktree (e.g., read-text-file, which, shell-env), process::command, http-client, etc.
  • crates/extension_api/src/process.rs, crates/extension_api/src/http_client.rs, crates/extension_api/src/settings.rs.
• Docs
  • docs/src/extensions/developing-extensions.md: how Zed extensions are structured and built.
  • docs/src/extensions/slash-commands.md: adding slash commands.
  • docs/src/configuring-zed.md: JSONC config files (user and project).
• Examples
  • extensions/slash-commands-example: minimal Rust extension with slash commands.
  • extensions/test-extension: shows process::Command, platform detection, simple FS operations inside the extension working directory.
• Extension metadata
  • extension.toml: manifest and capability declarations (e.g., [[capabilities]] kind = "process:exec").

These pieces create a safe and portable extension system, but we lack:

• A built‑in, dynamic scripting language.
• A small, opinionated set of general editor events and action registration surfaces for scripts to use.

Goals: Extensibility, Customizability, Introspection

• Extensibility: Let users add new commands, macros, and small features without compiling Rust.
• Customizability: Let users tailor behavior conditionally (e.g., project‑specific tweaks, quick transforms).
• Introspection: Allow read‑only access to buffer/project state, and small, safe mutations (insert edits, run actions).
• Developer loop: “Edit a script → reload → try” in seconds; no toolchain required for simple tweaks.

Emacs’ magic is not only “Lisp,” but the combination of a live runtime, a rich set of editor hooks, and a small, composable API surface. Zed can get close within its model.

Why Rhai?

Rhai (https://github.com/rhaiscript/rhai, https://rhai.rs) is an embeddable scripting engine written in Rust, designed for safety and tight host control. It fits Zed’s WASM+capabilities model.

Pros

• Rust‑native and WASM‑friendly: Pure Rust, compiles to wasm32-wasi inside a Zed extension; no C FFI.
• Built‑in sandboxing: By default, scripts can’t do I/O or escape; you explicitly register host functions.
• Strong safety controls: Per‑engine limits for CPU/time and memory:
  • Engine::set_max_operations (hard budget on instruction count).
  • Engine::on_progress (kill long runs; timebox execution).
  • Engine::set_max_call_levels, set_max_expr_depths, set_max_string_size, set_max_array_size, set_max_map_size, set_max_modules, set_max_variables.
• Small and configurable: Feature flags disable unused language capabilities to keep binaries small; the Rhai book cites sub‑400KB WASM for a full engine (non‑gzipped), smaller with features off.
• Frictionless Rust interop: Register Rust functions, share “packages” (global modules), and control a custom module resolver. No GIL or external runtime to ship.

Cons

• Ecosystem familiarity: Smaller mindshare than Lua/JS; fewer off‑the‑shelf recipes.
• No built‑in coroutines: Cooperative/yield patterns require host orchestration.
• WASM limitations: eval_file and filesystem module loading aren’t available; you supply script text via the host (Zed’s Worktree.read_text_file) and/or implement a custom module resolver.

Why Not Lua (First)?

Lua is mature, fast to start, widely known (esp. for editors). But, for Zed specifically:

• Embedding into Zed’s WASM extensions is awkward: mainstream Lua runtimes are C/C++; typical Rust bindings (mlua/rlua) target native, not WASI WASM. You’d either:
  • Ship a non‑WASM native plugin path (not Zed’s model), or
  • Use experimental Rust‑only interpreters (less mature), and still solve sandboxing manually.
• Sandboxing is more manual: You must curate/remove io/os and lock down the standard library. It’s doable, but easier to get wrong than Rhai’s “no I/O unless exposed” by default.
• LuaJIT is not an option in WASM.

Lua remains attractive for user familiarity (and #13491 explicitly requests it), but Rhai integrates more cleanly with Zed’s existing WASM+WIT architecture and safety posture.

Other Options (Brief)

• Starlark: Python‑like, deterministic, safe config language; good for “programmable config.” Also Rust‑friendly in native, but not as turnkey in WASM as Rhai.
• QuickJS/JavaScript: Familiar, but heavier to embed in WASM extensions than Rhai; sandboxing and host API constraints need careful design.
• Python via PyO3: Good for out‑of‑process tools (called with process::Command), not ideal to embed in Zed’s WASM core or inside extensions (CPython + GIL + size + security).

Proposal: A “Rhai Scripting” Extension

A single extension that embeds Rhai and exposes a small, safe surface for scripts to define commands/macros and light text transforms.

User experience

• Scripts live under .zed/scripts/*.rhai in a project and/or user‑level folder.
• Provide slash commands:
  • /rhai:reload — compile/reload scripts.
  • /rhai:run <name> [args…] — run a named script function.
  • /rhai:eval <code…> — for quick experiments (capability‑guarded).
• Later, when host events exist, allow optional “hooks” scripts (on open/save/close/selection change).

Engine design

• One Rhai Engine per extension instance, configured with strict safety:
  • set_max_operations(N) with a small N (e.g., a few thousand ops) for interactive commands.
  • on_progress with a time budget (e.g., terminate >50–100ms).
  • set_max_* limits for memory and depth to prevent abuse.
  • Disable features via compile flags and runtime options as needed (e.g., disable modules unless a custom resolver is installed).
• Script loading:
  • Read via Worktree.read_text_file (see WIT worktree.read-text-file in crates/extension_api/wit/since_v0.6.0/extension.wit), not the filesystem.
  • Compile scripts to AST with Engine::compile and cache by path; expose /rhai:reload to rebuild on demand.
• Module resolver:
  • Provide a custom Rhai ModuleResolver that resolves import by calling back into the host to read from .zed/scripts/modules/ via Worktree.
  • Disallow arbitrary file import and enforce a strict module path prefix.

Minimal host API surface (no new Zed API required)

• Use existing slash command integration to expose Rhai runtime commands (run_slash_command in crates/extension_api/src/extension_api.rs).
• Route script outputs back as SlashCommandOutput for visibility.
• Optional bridges:
  • Safe text transforms: scripts can return edits as structured data; the extension applies them via host actions once available (see “Needed API additions” below).
  • External tools: selectively allow process::Command (requires manifest capabilities) if the user opts in.

Incremental hot‑reload

• Until file‑watch APIs exist, provide /rhai:reload.
• Document how to use “Install Dev Extension” and “Rebuild” for quick iteration (docs/src/extensions/developing-extensions.md).

Capabilities and security

• Do not expose filesystem/network to scripts.
• Only expose carefully vetted host helpers for text edits and queries.
• For any optional out‑of‑process calls, require explicit [[capabilities]] in extension.toml (e.g., process:exec).

Skeleton (Illustrative Only)

Cargo.toml (extension)

[dependencies]
zed_extension_api = "<compatible>"
rhai = { version = ">=1", default-features = false, features = ["std"] }

[lib]
crate-type = ["cdylib"]

Rust entry

use zed_extension_api as zed;
use zed::{Extension, SlashCommand, SlashCommandOutput, Worktree, Result};
use rhai::{Engine, AST};

struct RhaiExt {
    engine: Engine,
    scripts: std::collections::HashMap<String, AST>,
}

impl Extension for RhaiExt {
    fn new() -> Self {
        let mut engine = Engine::new();
        // Safety limits
        engine.set_max_operations(5_000);
        engine.on_progress(|ops| {
            // Optional additional time-based termination
            if ops > 100_000 { return Some(rhai::Dynamic::UNIT); }
            None
        });
        // TODO: register host functions here (safe helpers)

        Self { engine, scripts: Default::default() }
    }

    fn run_slash_command(
        &self,
        command: SlashCommand,
        args: Vec<String>,
        worktree: Option<&Worktree>,
    ) -> Result<SlashCommandOutput, String> {
        match command.name.as_str() {
            "rhai:reload" => {
                // Recompile `.zed/scripts/*.rhai` via Worktree.read_text_file
                Err("reload not implemented in sketch".into())
            }
            "rhai:run" => {
                // Lookup compiled AST, call a public function by name with args
                Err("run not implemented in sketch".into())
            }
            "rhai:eval" => {
                // Evaluate provided code (disabled by default; opt-in)
                Err("eval not implemented in sketch".into())
            }
            _ => Err(format!("unknown command: {}", command.name)),
        }
    }
}

zed::register_extension!(RhaiExt);

extension.toml (capabilities minimal)

id = "rhai-scripting"
name = "Rhai Scripting"
version = "0.0.1"
schema_version = 1
description = "Programmable scripts via Rhai"
authors = ["..."]
repository = "https://github.com/..."

# Add [[capabilities]] if you decide to allow process execution, otherwise none.

Needed Host API Additions (to unlock Emacs‑like use)

These align with open issues/discussions and keep the surface small and safe:

• Register custom actions (Discussion Allow registering custom actions from extensions #39554)
  • Let extensions define simple named actions callable via command palette and keybindings.
• Editor hooks (Issue Command palette/projects/text buffer extension API #18043)
  • Read‑only events: buffer opened/closed, selection changed, diagnostics updated, file saved.
  • Opt‑in mutable actions: apply text edits, insert snippets, set selection, etc.
  • All gated by manifest‑declared capabilities and disabled by default.
• Workspace exposure (Issue Expose Workspace to the Extension #20831)
  • Safe read‑only API: list open buffers, current project/worktree metadata.
• Webview (Issue Webview via Extensions #21208)
  • Optional for richer UI contributions; not required for scripts/MVP.

With these in place, the Rhai extension can:

• Bind action names → Rhai functions.
• Subscribe to events → call Rhai handlers with structured arguments.
• Apply safe edits returned by Rhai.

Comparison Recap

• Rhai

  • Best architectural fit for Zed’s Rust→WASM model; smallest embedding/sandboxing friction.
  • Strong built‑in safety/time/memory controls and clean capability gating via “register only what you need.”
  • Smaller ecosystem; no coroutines; import scripting via host module resolver.

• Lua

  • Most familiar for editor scripting; nice coroutine ergonomics.
  • Maturity and adoption are big wins.
  • Technical fit is weaker under Zed’s WASM constraints; sandboxing is more manual; LuaJIT unavailable.

• Others (Starlark/JS/Python)

  • Starlark: excellent for deterministic programmable config; narrower scripting surface.
  • JS/QuickJS: familiar but heavier in WASM extension and sandboxing work.
  • Python: ideal out‑of‑process (via process::Command), not in‑core.

Phased Plan

Phase 1 (no host changes)

• Ship “Rhai Scripting” extension:
  • Slash commands for reload/run/eval.
  • Script discovery .zed/scripts/*.rhai.
  • Engine safety limits and termination hooks.
  • Zero I/O exposure, no process execution by default.
• Document how to map commands to keybindings using existing Zed mechanisms (when custom actions are available, switch to those).

Phase 2 (small host additions)

• Add “register custom actions” and stable read‑only editor events.
• Add minimal “apply edits” host API (capability‑gated).
• Enhance the Rhai extension to wire actions ↔ scripts and run handlers on events.

Phase 3 (richer capabilities)

• Optional webview contribution.
• Broaden event coverage based on demand.
• Consider project/user‑level script packs published as extensions.

References (Issues & Discussions)

• add lua as an optional config language — add lua as an optional config language #13491
• Command palette/projects/text buffer extension API — Command palette/projects/text buffer extension API #18043
• Extension API: let extensions spawn local HTTP servers — Extension API: let extensions spawn local HTTP servers #20040
• Extension API: let extensions arbitrarily send and receive LSP messages — Extension API: let extensions arbitrarily send and receive LSP messages #20042
• Webview via Extensions — Webview via Extensions #21208
• Expose Workspace to the Extension — Expose Workspace to the Extension #20831
• Expose more LanguageSettings to Extensions API — Expose more LanguageSettings to Extensions API #21822
• Extension API: Support for external formatters — Extension API: Support for external formatters other binaries #31904
• Allow registering custom actions from extensions — Allow registering custom actions from extensions #39554
• Proposal for Lisp as the Extension Mechanism — Proposal for Lisp as the Extension Mechanism #14539
• Improve agility by offloading to extensions and scripting — Improve agility to agent support by offloading it to extensions and scripting #38249

Code Pointers (Stable Names)

• Extension trait and registration macro: crates/extension_api/src/extension_api.rs (Extension, register_extension!, run_slash_command, complete_slash_command_argument).
• WIT definitions (worktree, process, http client, slash commands): crates/extension_api/wit/since_v0.6.0/extension.wit.
• Dev guide: docs/src/extensions/developing-extensions.md.
• Slash commands guide: docs/src/extensions/slash-commands.md.
• JSONC settings: docs/src/configuring-zed.md.
• Example extension: extensions/slash-commands-example.
• Test extension showing process/HTTP/platform helpers: extensions/test-extension.

Closing

Zed’s Rust→WASM foundation is the right bedrock for speed and safety. A small, dynamic scripting layer—implemented as a Rhai‑powered extension—can deliver everyday hackability without compromising that bedrock. Start minimal with slash commands and reloadable scripts; evolve toward Emacs‑like power by adding a small, capability‑gated host surface for actions and events. This path aligns with active community requests and keeps Zed fast, safe, and delightfully programmable.

[ariawisp]

I'd rather see official support for WIT (Wasm Interface Type - see wit-bindgen) bindings for the Zed extensions API for other mainstream languages, along with an expanded Zed extension API with more capabilities, and improved tooling for extension development.

JS/QuickJS: familiar but heavier in WASM extension and sandboxing work.
Python: ideal out‑of‑process (via process::Command), not in‑core.

Both JavaScript and Python are documented on the WebAssembly Component Model website as being usable for WASM component creation. This means Zed extensions could be developed in JavaScript and Python (and other languages) and compile as WASM components, the same way Zed's currently supported Rust extension system works.

• JavaScript Tooling
• Python Tooling

Zed’s Rust/WASM extensions are fast and secure but require a compile step. This slows the “tweak → eval → iterate” loop that makes Emacs compelling.

Is the compile step really the bottleneck? With Zed's existing Wasmtime engine, extensions can already be reloaded without restarting the entire Zed editor (as seen today when you install an extension). A dev-mode hot-reloading system for extensions could be built with the current architecture without adding a scripting language.

Optional webview contribution

I think a GPUI-based UI contribution for extensions would be a better fit than WebView for Zed's performance goals.

Cons: Ecosystem familiarity: Smaller mindshare than Lua/JS; fewer off‑the‑shelf recipes.

Furthermore, this makes Rhai less viable for LLM-assisted code generation compared to mainstream languages.

---

Overall, Rhai seems redundant with Wasmtime and the WebAssembly Component Model that Zed already uses for extensions, while also being less production battle-tested than mainstream languages. I think a better direction for Zed's extension development would be focusing on expanding the extension API itself, bringing support for authoring extensions to other mainstream languages via the WebAssembly Component Model, and improving the development flow for extensions (i.e. hot reloading in Wasmtime).

If you haven't already, I recommend reading Life of a Zed Extension: Rust, WIT, Wasm and watching the associated YouTube video to help understand the current extension architecture.

[ariawisp]

One more thing: This proposal appears to lack any mention of how a Rhai scripting system would reconcile with Zed's evolving extension API versioning (a problem they have already meticulously solved with the WIT-based approach).

How would you ensure Rhai scripts remain working, validate version compatibility, and maintain access to the latest extension API features and changes, as Zed's extension API evolves version-after-version? Especially with the idea of "project/user‑level script packs published as extensions."

---

To give an example from the "Needed Host API Additions" in your proposal:

Workspace exposure: Safe read‑only API: list open buffers, current project/worktree metadata.

What happens when "current project/worktree metadata" changes its structure in a new Zed version, but active Rhai scripts are still expecting the old structure?