Core Concepts

Extending — Plugins & WASM

Add tools, compressors, chunkers and providers without forking LeanCTX. Declare a tool in a plugin manifest, react to lifecycle hooks, or compile a custom transform to a sandboxed WASM module — each is discovered, advertised in /v1/capabilities and conformance-checked like a built-in.

Need a domain tool or a compressor tuned to 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. Every extension is discovered automatically, advertised in /v1/capabilities, and proven by the conformance suite.

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

Declare a tool in plugin.toml. LeanCTX registers it as a native MCP tool at startup and advertises it in /v1/capabilities alongside the built-ins: 

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

[[tools]]
name = "crm_lookup"
description = "Look up an account in the CRM"
command = "crm-bin"                 # JSON args on stdin, 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, so they add no overhead to the hot path.

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

Compile your transform to a sandboxed WASM module — in 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=~/.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

Trust model & conformance

Every extension runs under the same trust model: a scrubbed environment, a cwd jail, an execution timeout, and declared permissions surfaced for consent. 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. Run lean-ctx conformance to prove an extension behaves like a built-in, and manage installed plugins with the ctx_plugins tool or lean-ctx plugin.

Under the hood

Plugins live in core/plugins/ (manifest tools + hooks); the WASM host is core/wasm_ext.rs. Both feed the same capability registry that /v1/capabilities exposes and that conformance checks — so a third-party extension is genuinely first-class, not a second-tier add-on.

Where to go next