Journey: Extend Without Forking: Plugins & WASM

You need a domain tool (an internal lookup) and a custom compressor for your data shape. Forking the engine and maintaining a patched build is a non-starter. LeanCTX gives you three escalating ways to extend it, none of which touch its source.

---

1. A tool the agent can call — a plugin manifest

LeanCTX registers it as a native MCP tool at startup and advertises it in /v1/capabilities:

# plugin.toml
[plugin]
name = "crm"
version = "0.1.0"

[[tools]]
name = "crm_lookup"
description = "Look up an account in the CRM"
command = "crm-bin"                 # gets JSON args on stdin, returns text on stdout
timeout_ms = 8000
input_schema = { type = "object", properties = { account = { type = "string" } }, required = ["account"] }

[trust]
permissions = ["network"]          # declared + surfaced for consent

2. React to lifecycle events — hooks

Declare a command per event — pre_read, post_compress, on_knowledge_update, on_session_start / on_session_end. Hooks are zero-cost when nothing listens.

3. A custom compressor / read-mode / chunker — WASM

Compile it to a sandboxed WASM module (any language) and drop it in a directory; LeanCTX discovers it by file stem and registers it as a first-class extension:

export LEAN_CTX_WASM_DIR=~/.local/share/lean-ctx/wasm    # *.wasm → registered compressors
lean-ctx conformance                          # your extension is checked like a built-in

/v1/capabilities → extensions.compressors: ["identity","markdown","prose","whitespace","my_ext"]
conformance scorecard → [ok] extensions/compressor:my_ext

4. Under the hood — core/plugins/ + core/wasm_ext.rs

Plugins fire hooks and register manifest tools; the WASM host implements wasm-abi-v1 (alloc + lctx_compress / lctx_provider_fetch) with a host-enforced byte budget, so a faulty guest can never overrun. Everything runs under the extension trust model, scrubbed env, cwd jail, timeout, declared permissions surfaced for consent, and is proven by the conformance suite.

Payoff

The engine is extensible in any language, sandboxed, discoverable and conformance-checked, your tools and transforms are first-class without ever touching LeanCTX’s source.