The extension host exposes explicit lifecycle/tool/context seams while keeping the default UI and assistant loop Go-owned. New APIs are designed as runtime-neutral host contracts first and then exposed through Lua.
Current lifecycle events include:
| Event | Purpose | Mutation policy |
|---|---|---|
session_start / session_load / session_shutdown |
Observe session lifecycle. | Observational initially. |
input / prompt_prepare |
Inspect or eventually transform user input before a turn. | Explicit transforms only. |
turn_start / turn_end / agent_end |
Observe one assistant turn. | Observational initially. |
context_build |
Add bounded, labeled context blocks and inspect context budgets. | Bounded contributions only. |
before_provider_request / after_provider_response / provider_error |
Observe provider traffic with redacted payloads. | Conservative typed mutation only. |
tool_call / tool_result / tool_error |
Mediate tool execution and results. | Normalize arguments; rewrite/redact results; surface hook errors as tool errors. |
message_append |
Observe durable message writes. | Observational initially. |
All lifecycle payloads must be bounded. Provider events must redact auth headers and secrets. Tool hook decisions should be visible in diagnostics.
librecode separates two event mechanisms:
- the ro-backed event stream for observational async/fanout events such as lifecycle telemetry, headless JSON output, timers, retry notifications, and future watchers
- the ordered middleware dispatcher for hooks that return mutations, such as tool normalization/redaction, context contributions, and provider request changes
Extensions may observe lifecycle events through Lua handlers, while core Go services can subscribe to the reactive stream for telemetry and integrations. Do not use the observational stream for state mutations that require deterministic ordering.
This document describes the currently implemented Lua API surface.
It is intentionally practical and code-oriented. The API is still evolving as librecode moves toward a more programmable runtime.
See also:
docs/adr/0001-programmable-runtime.mddocs/runtime-architecture.mddocs/extension-runtime.mddocs/extension-roadmap.mddocs/rendering-boundary.md
Extensions are trusted local Lua files loaded from configured extensions.use sources.
Default config:
extensions:
enabled: true
use:
- path:.librecode/extensionsSupported source declaration forms:
extensions:
use:
# shorthand string form
- official:vim-mode
- github:example/librecode-extension
- github:example/monorepo//extensions/fancy
- path:.librecode/extensions/my-extension
- path:/absolute/or/relative/extension
# object form with version pinning
- source: official:vim-mode
version: v0.1.0
- source: github:example/librecode-extension
version: v1.2.3Startup loads only entries declared in extensions.use; extra directories on disk are ignored. path: sources load from disk today. official: and github: sources are installed and pinned by the extension manager. Unknown schemes are configuration errors.
librecode does not auto-load a bundled extensions/ directory. The stock chat UI is implemented in Go; Lua extensions are optional customization. Use --no-extensions to skip configured extensions for one command.
Each Lua file or directory extension entry runs in its own Lua state. Directory extensions use a small manifest plus entry file:
.librecode/extensions/my-workflow/
init.lua
workflow.lua
helpers.lua
-- init.lua
return {
name = "my-workflow",
version = "0.1.0",
api_version = "v1alpha1",
entry = "workflow.lua",
}The extension root is added to package.path, so entry files can require sibling modules:
local helpers = require("helpers")Helper modules are convenience wrappers over primitive APIs. They are not a separate Go host API family.
Extensions can either use the global librecode table or require the module explicitly:
local lc = require("librecode")Registers a low-level event handler.
local lc = require("librecode")
lc.on("prompt_submit", function(ev)
lc.event.consume()
lc.buf.append("transcript", {
kind = "message",
role = "custom",
text = "extension intercepted submit\n",
})
end)Variant with priority:
lc.on("key", { priority = 100 }, function(ev)
return true
end)Current commonly emitted events include:
startupkeyprompt_submitprompt_user_entryprompt_doneretry_startretry_endmodel_deltathinking_deltatool_starttool_endresizerendertickbefore_agent_startagent_endcontext_buildbefore_provider_requestafter_provider_responseprovider_errortool_calltool_resulttool_error
Tool lifecycle handlers may return small, explicit mutations. librecode stays YOLO by default; these hooks are for formatting, observability, redaction, or argument normalization rather than built-in permission gates.
lc.on("tool_call", function(ev)
if ev.payload.name == "read" then
return {
tool_call = {
arguments = {
path = ev.payload.arguments.path,
limit = 200,
},
},
}
end
end)
lc.on("tool_result", function(ev)
if ev.payload.name == "bash" then
return {
tool_result = {
result = ev.payload.result:gsub("SECRET=[^\\n]+", "SECRET=<redacted>"),
},
}
end
end)librecode extension list reports registered commands, tools, keymaps, handlers, active timers, and cumulative Lua execution duration per loaded extension. Use it with --no-extensions comparisons to isolate extension-induced UX or performance issues.
Writes a message through the Go logger.
lc.log("hello from extension")Registers an extension command.
lc.register_command("hello", "print hello", function(args)
return "hello " .. (args or "")
end)The command appears in librecode extension list and can be executed with librecode extension run <name>.
Registers an extension-backed tool callable by the runtime.
lc.register_tool("echo_json", "returns the provided args", function(args)
return {
content = "ok",
details = args,
}
end)Handlers receive a Lua table converted from Go map[string]any arguments.
They may return either:
- a scalar/string-like value, which becomes tool content; or
- a table with:
contentdetails
Neovim-inspired low-level helpers.
Returns a stable numeric namespace ID for the provided name.
local ns = lc.api.create_namespace("my-extension")If called again with the same name, returns the same ID.
Registers event handlers for one or more event names.
Examples:
lc.api.create_autocmd("prompt_submit", function(ev)
lc.log("submit seen")
end)
lc.api.create_autocmd({ "before_agent_start", "agent_end" }, {
priority = 50,
callback = function(ev)
lc.log("lifecycle event")
end,
})Also available as:
librecode.api.nvim_create_autocmdlibrecode.autocmd.create
Registers a user command.
lc.api.create_user_command("Hello", {
desc = "say hello",
callback = function(args)
return "hello"
end,
})Also available as:
librecode.api.nvim_create_user_commandlibrecode.command.create
Registers a keymap against a generic target.
Examples:
lc.keymap.set({ focus = "composer" }, "ctrl+j", function(ev)
lc.buf.set_text("status", "ctrl+j pressed")
return true
end, { priority = 100, desc = "example composer keymap" })
lc.keymap.set({ buffer = "composer" }, "*", function(ev)
lc.log("focused composer buffer key: " .. ev.key)
end)
lc.keymap.set("global", "ctrl+p", function()
lc.action.run("transcript.tree")
return true
end)Supported target forms:
"global"for global keymaps{ focus = "name" }for focused target kind keymaps, such ascomposer,autocomplete, orpanel{ buffer = "name" }for focused-buffer keymaps{ window = "name" }for focused-window keymaps{ role = "name" }for focused-role keymaps{ scope = "focus" | "buffer" | "window" | "role", name = "name" }- a list of any of the above
String targets other than "global" are shorthand for role-scoped keymaps. Prefer explicit target tables for clarity. Non-global keymaps match the currently focused target only, not every visible window. This keeps composer extensions from stealing keys while autocomplete or panels are focused.
Notes:
lhsis normalized internally (<c-j>,ctrl-j, andctrl+jnormalize together)"*"or"any"matches any key- higher
priorityruns first - returning
truemarks the event consumed
Removes matching keymaps previously registered by the same extension.
All mutable runtime APIs currently work only during active event handling. Calling them outside an event raises an error.
Window APIs expose and mutate the currently visible runtime windows for the active event.
Returns visible window names.
Returns the named window table or nil.
Fields currently include:
namerolebufferrendererxywidthheightcursor_rowcursor_colvisiblemetadata
renderer = "default" means the stock Go renderer may draw the window. renderer = "extension" means the extension owns the window until a later window/layout mutation changes it, so the stock renderer skips that window.
Finds the first matching window.
Supported filters today:
namerolebuffer
Example:
local win = librecode.win.find({ role = "composer" })
local buf = librecode.win.get_buf(win)Returns the buffer name displayed by the given window.
This is the current path for extensions that want to discover the composer through the visible runtime model instead of assuming a hardcoded buffer name.
Mutate the active window set. Window mutations are applied back to the terminal runtime after the event.
Use librecode.win.set_renderer(name, "extension") or set window.renderer = "extension" before win.set/layout.set when an extension wants to fully own that window's drawing. Set it back to "default" to return drawing to the stock renderer.
Layout APIs expose the current screen dimensions and window table.
Returns a table:
{
width = 120,
height = 40,
windows = {
composer = { role = "composer", buffer = "composer", x = 0, y = 32, width = 120, height = 6 },
},
}Replaces the runtime layout with the provided table. This is intentionally low-level: callers are responsible for non-overlap, bounds, and visibility.
Low-level drawing APIs enqueue window-relative draw operations for the current frame/event.
Current UI primitives are intentionally small. They are enough for optional overlays and focused custom windows, but not yet enough to faithfully reimplement complex hot renderers such as the transcript. See docs/rendering-boundary.md for the current rendering boundary.
Returns terminal display width in cells using the Go rendering backend's grapheme-aware width logic.
Returns text truncated to fit width cells. Truncation is grapheme-aware and appends an ellipsis when possible.
Returns text padded/truncated to exactly width cells.
Returns a list of wrapped lines using the same generic Go-backed wrapping logic used by stock renderers.
Returns a bounded viewport table for a line list:
lines— visible line slicestart/end— zero-based half-open range in the original line listoffset— clamped bottom-relative scroll offsetmax_offset— maximum valid offsettotal— original line count
Returns a bounded viewport table for variable-height items. Each item may be either a number or a table with height.
Returned fields:
items— visible item metadata withindex(zero-based),lua_index,row_offset, andheightstart/end— zero-based half-open item rangeoffset— clamped bottom-relative scroll offset in rowsmax_offset— maximum valid row offsettotal— original item count
This is intended for large structured renderers so Lua can render only visible blocks while Go handles viewport math.
Returns supported theme token names for fg/bg style fields.
Styles currently accept fg, bg, bold, and italic. Color names are theme tokens resolved by Go, including text, accent, border, borderAccent, borderMuted, muted, dim, warning, error, success, selectedBg, userMessageBg, customMessageBg, and tool/diff/code tokens.
draw_spans accepts inline spans such as:
{
{ text = "hot", fg = "accent", bold = true },
{ text = " cold", fg = "dim" },
}Example:
lc.on("render", function()
local win = lc.win.find({ role = "composer" })
if not win then return end
lc.win.set_renderer(win, "extension")
lc.ui.clear_window(win)
lc.ui.draw_box(win, { fg = "border" })
lc.ui.draw_spans(win, 1, 2, {
{ text = "custom ", fg = "text" },
{ text = "composer", fg = "accent", bold = true },
})
lc.ui.set_cursor(win, 1, 2)
end)Still-planned generic UI primitives include namespace-scoped highlights/extmarks, richer window scroll state, and renderer registration helpers.
Returns visible buffer names for the current event.
Creates or replaces a buffer in the current event result.
lc.buf.create("notes", { text = "hello", cursor = 5 })Marks a buffer for deletion.
Returns a table containing the current buffer state.
Fields include:
nametextcharscursorlabelmetadata
Get or replace buffer text.
Get or replace cursor position.
Rune-oriented editing helpers for low-level buffer mutation.
Line-oriented helpers for replacing a range.
Replace the full buffer state.
Append text or one structured block to a buffer.
Examples:
lc.buf.append("status", "working")
lc.buf.append("transcript", {
kind = "message",
text = "tool finished\n",
role = "tool_result",
})String values append to buffer text. Tables with block fields append to buffer.blocks.
Clear buffer text, blocks, and cursor.
Structured block helpers. Blocks are generic and may be used for transcript items, tool output, annotations, or any extension-defined data.
Recognized block fields include:
idkindroletextindexcreated_atstreamingmetadata
Read or write buffer metadata values.
Request host-side runtime actions from an extension.
Current built-ins include:
submithistory.prevhistory.nextautocomplete.acceptfollowup.queuefollowup.dequeueinterruptprompt.canceltranscript.tree
Timer callbacks run at the start of the next terminal runtime event whose clock is past the scheduled time. They execute inside the same transaction model as event handlers, so they may use buf, win, layout, ui, and action APIs.
Schedules a one-shot callback and returns a timer ID.
Schedules a repeating callback and returns a timer ID.
Cancels a pending timer.
These helpers only make sense during active event execution.
Marks the event as consumed.
Marks the event as consumed and stops later handlers.
Handlers for terminal events receive a table like:
{
name = "key",
key = "ctrl+j",
text = "",
ctrl = true,
alt = false,
shift = false,
working = false,
auth_working = false,
context = {
mode = "chat",
working = false,
auth_working = false,
cwd = "/path/to/project",
session_id = "abc",
},
data = {
text = "incremental event text",
},
focus = { kind = "composer", window = "composer", buffer = "composer", role = "composer", panel_kind = "", exclusive = false },
composer = { text = "hello", cursor = 5, chars = { "h", "e", "l", "l", "o" }, metadata = {} },
buffers = {
composer = { text = "hello", cursor = 5, chars = { "h", "e", "l", "l", "o" }, blocks = {}, metadata = {} },
status = { text = "", cursor = 0, chars = {}, blocks = {}, metadata = {} },
transcript = {
text = "",
cursor = 0,
chars = {},
metadata = { count = 12, snapshot_count = 12, snapshot_start = 0, snapshot_limit = 32 },
blocks = {
{ id = "message:0", kind = "message", role = "user", text = "hello", index = 0, streaming = false },
{ id = "streaming:11", kind = "streaming", role = "assistant", text = "partial", index = 11, streaming = true },
},
},
thinking = { text = "", cursor = 0, chars = {}, blocks = {}, metadata = { count = 1 } },
tools = { text = "", cursor = 0, chars = {}, blocks = {}, metadata = { count = 1 } },
},
}A project extension can build substantial behavior using the current API:
local lc = require("librecode")
lc.keymap.set({ focus = "composer" }, "<c-j>", function()
lc.action.run("submit")
lc.event.consume()
end)Useful patterns include:
- event-driven state
- keymaps
- composer editing
- label updates
- low-level buffer mutation
The extension host also emits bounded lifecycle events around the assistant runtime. These are runtime-neutral host events exposed through Lua as regular lc.on(...) handlers. Handlers may observe payloads and return { stop = true } to prevent later handlers from running, but session/input/turn events are observational in the current release.
Current assistant lifecycle events include:
inputprompt_preparesession_startsession_loadbefore_agent_startagent_startturn_startcontext_buildbefore_provider_requestafter_provider_responseprovider_errortool_calltool_resulttool_errormessage_appendturn_endagent_end
Example:
local lc = require("librecode")
lc.on("turn_start", function(event)
lc.log("turn started for session " .. event.payload.session_id)
end)
lc.on("message_append", function(event)
lc.log("appended " .. event.payload.role .. " entry " .. event.payload.entry_id)
end)
lc.on("context_build", function(event)
event.payload.contributions = {
{
name = "project-constraints",
source = "my-extension",
role = "system",
content = "Prefer small focused commits and run the project CI before committing.",
},
}
return { payload = event.payload }
end)Lifecycle payloads are intentionally bounded. message_append includes the appended entry text and metadata for the current message, but lifecycle events do not include full transcript history.
context_build has a bounded mutation contract. Handlers may return contributions entries. Each contribution must include non-empty content and is capped by the host. The context payload exposes breakdown.system, breakdown.skills, breakdown.history, and breakdown.extensions token estimates so extensions can reason about context budget without seeing the full transcript.
before_provider_request has a conservative mutation contract. The payload exposes request metadata, a redacted header map, and a provider payload object. Handlers may return a modified payload and provider_request.headers for non-sensitive headers:
lc.on("before_provider_request", function(event)
event.payload.payload.metadata = "debug-marker"
return {
payload = event.payload,
provider_request = {
headers = {
["X-Debug-Run"] = "local",
},
},
}
end)Sensitive headers such as Authorization, x-api-key, cookie, and proxy-authorization are redacted in payloads and cannot be modified by provider hooks.
The API is still incomplete compared with the long-term target.
Notably missing today:
- job/process spawning primitives
- optional Lua helper modules built on primitive APIs
- highlights/extmarks/namespaced annotations
- deeper assistant/model/tool runtime replacement hooks
Future APIs should preserve the primitive-first boundary described in docs/runtime-architecture.md: add kernel primitives to Go, and build product convenience in Lua.