← Reference

Plugin runtimes

Extension surfaces registered into plugin-host.

Full notes from the app

Every session builds its own plugin stack: plugins from the built-in root (~/.kcode/plugins-builtin: kcode-managed, refreshed every boot, and anything there the build doesn't ship is deleted), ~/.kcode/plugins, and <project>/.kcode/plugins load into the session's live tool registry (each plugin is a folder holding plugin.toml, whose kind line says how it runs: "Lua", "Mcp" or "Content"; a manifest without one fails to load, and /plugins lists it under Failed to load with why; a hidden folder, its name starting with ., is not a plugin), MCP servers come from .mcp.json, and plugins hot-reload on change, one added while a session runs loads into it, its plugin folder followed whether made yet or not; a project plugin new or changed since you trusted the project waits for your answer to the trust question. Headless (kcode -p) gets the same stack. A plugin bundle can also ship content dirs alongside its runtime, all five domains: <plugin>/commands/*.md and <plugin>/skills/*.md load into the slash-command and skill registries, <plugin>/agents/*.md into the agent-kind registry, <plugin>/output-styles/*.md into the output-style picker, and <plugin>/themes/*.ron|*.json into the theme catalogue. Every domain loads after the built-in bundle and the configured user/project sources, so those win a name collision, and a plugin blocklisted in <project>/.kcode/policy.toml contributes no commands, skills, agents or output styles to that project's sessions: themes are the window's, so a project's policy drops only its own plugins' themes; commands/skills/themes hot-reload with the rest of the plugin, agents and output styles apply to newly-built sessions. Authoring is a guided path: kcode plugins scaffold <name> [--project] emits a complete working Lua skeleton (manifest, main.lua demonstrating tools + event hooks + kv storage, a bundled command and skill); kcode plugins validate <path> then runs the same checks a session load runs: manifest shape (a kind line included), a real runtime load (Lua syntax errors, duplicate tools), and every bundled command, skill, agent, output style and theme file read by its own loader, with an agent's permission_mode checked too. Lists what the plugin registered in code (tools, event hooks, intercepts, provides, and a Lua plugin's kcode.on_cron schedules and slash commands), and exits non-zero on failure, naming each file that fails. Worked examples live in examples/plugins/ in the repo. Local trust: a manifest declares the host APIs it uses in a [capabilities] table (kv = true, hooks = true; durable storage / event hooks: tool registration is never gated), and may declare named schedules, [[triggers.cron]] (six-field cron, seconds first, weekdays counted as in crontab: 1 Monday, 0 or 7 Sunday) and [[triggers.every]] (plain durations in ms, s, m, h, d or w: "30s", "5m", "15d"), validated at load (hooks grant required, unique names, periods parse, cron expressions checked by kcode plugins validate and again at registration); a schedule fires once for the whole app by default, in one open session that loaded the plugin (the next one takes over when it closes), or in an app plugin's one copy even with no session open: fires_per = "project" fires it once in each open project and fires_per = "session" in every open session, and an app plugin takes neither; durable = true keeps an app or project schedule's next time across restarts, and missed = "once" (the default) or "skip" says whether a time that passed while kcode wasn't running fires once at start; each firing publishes an owner-attributed core.timer.tick event the plugin hears via kcode.on_event("core.timer.tick", …), and a plugin.toml edit hot-reloads schedules with the rest of the plugin. A project can pin its plugin surface with <project>/.kcode/policy.toml (blocklist + required). kcode consumes nothing from Claude Code's plugin ecosystem (no Claude Code marketplace, name@marketplace installs or hooks). There is currently no public kcode marketplace; use kcode plugins install <folder> to install a local plugin. (.claude/rules/ interop stays via agents-md, and kcode loads AGENTS.md, never CLAUDE.md.)

9 entries · kcode 0.6.5097

9 shown
SurfaceLibraryInputScopeDescription
Luaplugin-runtime-luaLua scripts (main.lua + plugin.toml)Embedded: tools + events + kv + notify + inject + fetch + fs.read + input transforms + run-tool + subagents + timers + watch/intercept/provideEmbedded sandboxed Lua 5.5, shared with Lua script skills and bundled with kcode: no system Lua installation is required. A plugin is a folder holding plugin.toml and main.lua, and everything it does goes through the kcode table: Lua Plugin Calls lists each call, with its arguments, the capability it needs and what it returns. Each session loads its own copy of a plugin, unless its plugin.toml says loads_per = "app", which loads one copy for the whole app (App plugins). The sandbox has the table, string, math and utf8 libraries, with os, io, package, dofile, loadfile and debug left out. require("lib.words") loads lib/words.lua, or lib/words/init.lua, from the plugin's own folder (a script skill's from its skill folder) runs it once and returns what it returned (true when that was nothing); a name is letters, digits, _ and - in parts joined by dots, a file whose link leads out of the folder is refused, and an error names the file. A project plugin's whole folder is part of what project trust records, so a change to a file it requires asks again, as a change to main.lua does. A call the [capabilities] table doesn't grant fails with an error naming the plugin, the missing capability and the line that declares it. A manifest with an [events] table closes registration to what it names: kcode.on and kcode.on_event kinds must be under watch, kcode.intercept points under intercept and kcode.provide slots under provide, or the load fails naming the list to add the point to; no table leaves registration open to what the capabilities allow. kcode plugins validate reports every load error before a session loads the plugin.
MCPplugin-runtime-mcpMCP servers from .mcp.json (stdio command/args/env/optional cwd; http/sse). Stdio defaults to the declaring file's directory; a relative cwd resolves there.External: toolsModel Context Protocol clients. Declare servers in <project>/.mcp.json (Claude-Code-compatible command/args/env) or ~/.kcode/mcp.json; each server's tools register as <server>__<tool>, with every character a provider refuses in a tool name replaced by _ (and an m in front of a name that would not start with a letter). A name longer than 64 characters (the most OpenAI, DeepSeek and Gemini accept) keeps its first 55 and ends in _ plus eight hex digits of a hash of the whole name, the same on every connect; kcode still calls the server by the tool's own name. A tool whose server sends no inputSchema is offered to the model as taking an object with no listed arguments; one whose inputSchema names another type is left out, since no model could call it, and the log names it: MCP tool not registered. Every server connects when a session spawns: stdio, HTTP and SSE. Once they have connected or failed, a toast titled MCP servers over the session you are in lists them, one a line: each server with the number of tools it gave, or not connected and why, a warning when one isn't connected. The chat keeps no entry for them. A session with no MCP server shows no list. HTTP is MCP's streamable-HTTP transport: a server's session, replies sent as event streams, and the server's own message stream all work. An image a tool returns reaches the model as an image, shrunk to 2,000 pixels like any other, and the result's text keeps a note in its place; audio and other binary content are left out with a note naming their type and size. A server that sends its tool list in pages has every page read (only the first page was read, so the tools on later pages were missing); a server whose pages never end (it sends the same cursor twice, or more than 1,000 pages) fails to load, with the reason in the log. A tool's structured result (structuredContent) reaches the model beside its content, unless a text block already carries the same data as JSON (it was dropped, so a tool that sent its data only there answered with nothing). When the tool declares an outputSchema, a result that is not an error is checked against it, and one that breaks it, or carries no structured content, reaches the model with a note naming the problems. Stopping a turn stops a tool call still waiting for its server, and kcode tells the server with notifications/cancelled so it can stop too; so does a call that runs out of time. A tool its server marks read-only (readOnlyHint: true in the tool's annotations) is judged as a read: it runs without a prompt in every mode unless a rule denies it or its arguments name a secret location (permissions.secret_paths), runs beside the round's other read-only calls, and is offered to agent kinds held to reads; any other MCP tool needs permission unless a rule allows it. A hint that is not true, or annotations of an unexpected shape, count as no hint. A reconnect or a tools/list_changed refresh reads each listed tool again: one already registered takes its new description, schemas and read-only mark, and one whose new input schema no model can take is removed until a later listing gives it one.
Contentplugin-hostContent dirs only (plugin.toml with kind = "Content")Runtime-less: commands/skills/agents/output-styles/themesA runtime-less bundle: no scripts, no tools, just content dirs. Loading it records the plugin (it shows in kcode plugins list and the session stack) and skips runtime dispatch entirely; its content loads through the same five domain channels every bundle gets. kcode's own built-ins ship this way: the kcode-essentials bundle (the four built-in commands /init, /commit, /review, /security-review, the five agent kinds, the two output styles) is materialized to ~/.kcode/plugins-builtin/kcode-essentials/ at every boot, which also deletes any file there the build no longer ships. Its agent kinds and output styles load before user/project sources, so they keep winning name collisions; its commands load after them, so your own commit.md (or a plugin's) replaces the built-in /commit, and a project that blocklists kcode-essentials in policy.toml runs without the built-ins entirely.
Capabilitiesplugin-host[capabilities] table in plugin.toml: on/off grants (kv, hooks, notify, input-transform, inject, tool-gate, run-tool, spawn-subagent, "sessions.open", exec, answer-waits, presence, "history.read", "history.read-all", "plugins.stage", "sessions.all", replace-builtin, prompt) and scoped lists ("net.http", "fs.read", "fs.write", jobs)All runtimes: host-API grantsA plugin declares the host APIs it uses in its manifest's [capabilities] table. Safe grants are on/off: kv for the durable kv_* storage family, hooks for kcode.on_event / kcode.on / kcode.intercept / kcode.provide and the short forms kcode.on_input / kcode.on_tool, and [[triggers.*]] schedules, notify for kcode.notify, inject for kcode.inject (wake the session with an agent-visible <cp:plugin-inject> injection: joins an in-flight turn's next round or drives a wake turn when idle), run-tool for kcode.run_tool (run any session registry tool with the permission engine deciding each call and the plugin named as the caller), and spawn-subagent for kcode.spawn_subagent (start an attributed background subagent: plugin:<name>[:<label>] in the panel and the lifecycle events; rate-capped at 5 spawns per 600 s per plugin by default, plugin_host.spawn_subagent.*), and "sessions.open" for kcode.sessions.open (start a session in any folder, with a first prompt sent as the plugin's; the install review names it, nothing asks again when the plugin uses it, a project's trust still applies to the session it opens, and the daemon caps each plugin at 5 opens per 600 s by default, session_daemon.plugin_open_*), and exec for kcode.exec (run a program on this Mac with no shell; the install review walls it, and nothing asks again when the plugin uses it, but a deny rule of the user's and another plugin's veto at core.shell.pre still refuse a run), and answer-waits for kcode.waits (answer the permission asks and questions the plugin's own session waits on, as a window would: allow a tool call once or deny it, or pick a question's options; the install review walls it, since it can approve tool calls, and a deny rule of the user's still refuses the call before anything asks), and presence for kcode.presence() and for watching core.app.presence-changed (whether the user is at the Mac and sees the session; the install review walls it, since with it a plugin can time what it does (answering waits, say) for when the user is away, and a watch of the point without it fails the load naming the grant), and "history.read" for kcode.sessions.list and kcode.sessions.read (read the past sessions of the plugin's own project, what was said and every tool's output; "history.read-all" reaches every project's; the install review walls both, since a session holds whatever was typed or read in it), and "plugins.stage" for kcode.plugins.stage (write a plugin as a draft, which the user reviews and installs in Settings › Plugins; the install review walls it, since an installed draft can replace a plugin of the user's own), and "sessions.all" for hearing every session's core.app.* events (only a plugin with loads_per = "app" may declare it: see App plugins; the install review walls it, since such a plugin hears what every session in every project does, the agent's replies included). The intercept powers are on/off too: input-transform for kcode.on_input alone (rewrite or veto the user's prompt before the model is chosen: the short form of intercepting core.input.submit; vetoes land in chat attributed to the plugin), tool-gate for kcode.on_tool alone (a blocking pre-tool gate that can veto any tool call with a plugin-attributed reason: the short form of a gate at core.tool.pre; fail-open on error or timeout, so the session permission engine stays the security boundary) (hooks covers both short forms as well, because it covers every intercept point) and replace-builtin (shadow a safety-critical built-in (bash and the shell_* tools, fs_write/fs_edit/apply_patch, run_tests/test_cancel) which also needs project trust and the install-review approve; the original stays reachable as builtin:<name>), and prompt for kcode.intercept("core.prompt.build", …), the one intercept point that needs a grant on top of hooks, because it reshapes the agent's system prompt for the whole session; an intercept there without it fails the load naming the grant, and the install review walls it like the other intercept powers. Risky grants take a scoped list: "net.http" for kcode.fetch (host-mediated HTTP with any method, by default a 64 MB cap and 600 a minute per plugin, plugin_host.fetch.*) names the otherwise-fenced hosts (loopback, private, metadata) the plugin may reach, each read as a url(…) permission rule reads its host (*.corp.lan covers corp.lan and every host under it, 0x7f.1 is 127.0.0.1), and an empty list means any public host with the fenced class denied; you can let a plugin reach more fenced hosts yourself under [plugin_grants.<name>] net_http in your own config.toml, which counts only while the manifest asks for "net.http"; the fence judges every address a fetch connects to, an IPv6 form of a private address, a name that resolves to one, and each redirect included; "fs.read" for kcode.fs_read/fs_list and "fs.write" for project file writes list the allowed path globs (project-root-scoped via path-guard), an empty "fs.read" list reads the whole project, an empty "fs.write" list writes nothing. The install review walls an "fs.write" glob whose first folder or file name holds a wildcard (**/*, *.md) since it writes files the list never names, and names it (fs.write to broad paths: **/*); src/** or {docs,notes}/*.md stays an advisor. A write inside a git folder: a .git at any depth, in any letter case, where git keeps the hooks and config it runs programs from, goes through only when a glob names that folder (.git/hooks/**, vendor/*/.git/config); ** or src/** never writes there. The install review walls a glob that names one (fs.write into git folders (git runs their hooks as programs): .git/hooks/**). jobs for kcode.jobs.start and for watching core.app.job-finished (run the model in the background on a task the plugin names and hear its answer) lists the tools a job may call (jobs = ["fs_read", "grep"]) and jobs = [] runs jobs that call none; a job that names a tool outside the list is refused, and the install review walls the grant and names the tools (jobs (can run the model in the background with fs_read, grep, spending your tokens)), since a job spends tokens and acts with them. Registering tools needs no grant: that's a plugin's baseline purpose, and what its tools do is governed by the session permission gate like any other tool call, which judges each by what it declares, a tool that takes a built-in's name included. An undeclared call fails with an error naming the plugin, the capability by its manifest key and the exact line to add to [capabilities], scoped to what the call needed: the folder of the file it read or wrote, the local host it fetched (a script skill is pointed at its SKILL.md frontmatter instead); an unknown key in [capabilities] fails validation, and a manifest still using the old permissions = [...] list is rejected with a pointer to [capabilities] (kcode plugins validate catches all of these before a session ever loads the plugin). /plugins lists each plugin's grants, and under Failed to load each plugin folder whose last load or reload failed, with the reason (a manifest that does not parse, a missing grant) while the session's start notice and /debug name the folder; a failed reload says the plugin runs on as last loaded, and saving a fix clears the entry.
Declared eventsplugin-host[events] table in plugin.toml: watch, intercept and provide lists of point namesLua: registrationA plugin may declare the points it attaches to, by verb, in its manifest's [events] table: watch for kcode.on / kcode.on_event kinds, intercept for kcode.intercept points, provide for kcode.provide slots. With the table present, a registration the table does not name fails the load with one message naming the plugin, the list and the point to add (plugin x does not declare core.tool.pre under [events] intercept in its plugin.toml — add it there): the same shape as an undeclared capability call. Without the table, registration stays open to what the capabilities allow. kcode plugins validate checks the table before anything loads: any non-empty list needs the hooks grant, every name must be a catalogue point its verb supports (a retired, planned or unknown name is refused with the catalogue's reason), an intercept entry for core.prompt.build needs the prompt grant beside hooks (refused with the same message the runtimes raise), and a plugin whose code registers outside its table fails validation too. The table is part of the install hash, so editing it in an installed package deactivates the plugin until it is reinstalled. It is shown, never walled: the install review lists it beside the capabilities (Events: watches …; intercepts …; provides …), and Settings › Plugins, /plugins, kcode plugins list and kcode plugins install print the same line, not declared (may attach wherever its capabilities allow) for a plugin without the table; Settings › Plugins, /plugins and kcode plugins list print no line for a plugin that runs no code.
App pluginsplugin-host, agent-runtimeloads_per = "app" in plugin.tomlLua: one copy for the whole appA Lua plugin loads in each session by default, bound to that session's project and conversation. loads_per = "app" in its plugin.toml loads it once for the whole app instead: one copy in kcode's background process, which starts when kcode starts, before any session opens, and stops when kcode quits. Use it for state the sessions share: a count of turns across projects, or a ping to your phone when any session finishes. With hooks and "sessions.all" it hears every session's core.app.* events but core.app.presence-changed and core.app.job-finished, which belong to one session; each event's data names the session it came from under session (id, project_root, project, title). Its [[triggers.*]] and kcode.on_cron schedules, which it hears as its own core.timer.tick, and its kcode.after timers run in its one copy, even with no session open, so a schedule's fires_per can only be "app". It may declare only kv (your own storage, never a project's), hooks, notify, "net.http", exec and "sessions.all", and kcode.exec runs in your home folder under your own deny rules. It has no tools and no commands, attaches no intercept or provide, and can't call kcode.emit, kcode.session, kcode.ask_user or kcode.register_command, since each of those needs one session; a manifest or a call that tries is refused, naming the plugin and the rule, and kcode plugins validate checks the manifest the same way. kcode.notify posts a notification that belongs to no session and offers no command, at most 5 per 60 seconds for each app plugin (session_daemon.agent_notify_*). An app plugin loads from the built-in folder, your plugins folder or a link, never from a project's folder, since no project's trust covers the whole app. Its settings, secrets and off switch apply at once, and an edit to its files loads it again. Settings › Plugins and kcode plugins list mark it loads once for the app; its Settings detail shows its activity with or without a session open, and nothing about a session. /plugins lists a session's own plugins, so an app plugin is not there. "sessions.all" on a plugin that loads in each session is refused.
Project policyplugin-host<project>/.kcode/policy.tomlPer-project: block/require pluginsA committed-to-the-repo policy for the project's plugin surface: [plugins] blocklist = ["name"] refuses those plugins on every load path (discovery, hot reload, manual), including their bundled commands, skills, agents and output styles, so a blocked plugin contributes nothing to the project's sessions and its policy reaches no other project's; themes are the window's, one for every project, so the policy drops only the project's own plugins' themes, and required = ["name"] flags any listed plugin or MCP server that isn't loaded. Violations surface in /plugins under a Project policy heading and as a startup notification. Unknown keys are a hard parse error (a typo'd rule must never silently unenforce); a malformed file never blocks plugins but is itself reported the same way.
Authoring CLIplugin-authoringkcode plugins scaffold / kcode plugins validateCLI: authoringscaffold <name> [--project] emits a working Lua skeleton into ~/.kcode/plugins (or <project>/.kcode/plugins): a manifest, a main.lua that loads clean and demonstrates a tool + an event hook + durable kv, a bundled slash command and skill, which running sessions load at once (a project plugin needs the project's trust first) and /plugins lists, and a tests/test_main.lua that tests the tool and the hook under kcode plugins test; it refuses to overwrite, and refuses a name a plugin can't have (up to 40 lowercase letters, digits, - and _) before writing anything. validate <path> pre-flights any plugin dir with the exact checks a session load runs and exits non-zero on failure: fix before it ever reaches a session. It reads every file the bundle ships as its loader reads it: the frontmatter of each command, skill, agent and output style, and each theme file as the window loads it, and names each one that fails. An agent whose permission_mode names no mode an agent takes (only plan does) fails too, since it would load but not as written. Copyable examples: examples/plugins/ in the repo.
Testing CLIplugin-testkcode plugins testCLI: authoringtest <folder> [--timeout-secs <n>] runs a Lua plugin's own tests in kcode's own Lua 5.5, so code only another Lua accepts fails here as it fails in a session. Each test_*.lua file in the plugin's folder, and directly in its tests/ folder, runs in name order in a sandboxed Lua state of its own, where require reads the plugin's folder. Its top level adds tests with test(name, function() … end); assert_eq(actual, expected, message?) compares values, and tables key by key, and a difference fails the test naming both values and the file's line; print is kept and shown under a test that fails. Each test gets a fresh stand-in host: an empty project folder, empty storage and a clock that starts at 2026-01-01T00:00:00Z and moves only when the test moves it, and the plugin loads through kcode's plugin host and Lua runtime, with the grants its manifest asks for, on the first host call that drives it. A plugin with loads_per = "app" loads as the app loads it, so a call it can't make there fails the test the same way. Drive it with host.load(), host.call_tool(name, args?) (its structured result), host.fire(kind, data?) (how many handlers it reached), host.tick(name), host.intercept(point, payload) ({pass = true}, {veto = reason} or {rewrite = payload}), host.provide(slot, payload), host.command(name, args?) and host.advance(seconds), which runs each timer and schedule due on the way at its own time; each runs until the plugin's handlers, timers and questions settle, and fails the test with any handler error raised meanwhile. Set what the plugin reads with host.settings{…} (before it loads; a setting the manifest declares a secret goes to its secrets), host.session{…}, host.presence(…), host.waits{…}, host.add_session{…} (a past session for kcode.sessions.list and kcode.sessions.read, its records written in the shape a read returns; it returns the session's id), host.files{path = text}, host.kv_set(key, value) and host.set_time(rfc3339). Answer its calls out with host.on_tool(name, reply), host.on_exec(program, reply), host.on_fetch(url, reply) (a URL ending in * matches by prefix) and host.on_ask(reply): a value, or a function of the call's arguments; a call with no reply fails the test naming the call that gives one, and a question with none is dismissed. Read what it did, oldest first, with host.notices(), host.injections(), host.tool_calls(), host.fetches(), host.execs(), host.questions(), host.subagents(), host.jobs() (a job's id is job-1, then job-2 and on, and a test ends one with host.fire("core.app.job-finished", …), whose owner names the plugin), host.staged() (each draft kcode.plugins.stage wrote, its name and files; nothing is written, the answer's folder is plugins-staged/<name>, and its replaced is true for a name the test staged before), host.opened(), host.logs(), host.emitted() and host.wait_answers(), its schedules with host.schedules(), and its files and storage with host.file(path) and host.kv_get(key). Nothing leaves the machine: fetches, programs, sessions, subagents, jobs and drafts are answered or recorded, not run, and a tool the test calls runs without the permission engine or the plugins' gates. It prints each test with ✓ or ✗ and why, ends with result: OK (n passed) or result: FAILED (n passed, m failed), and exits 1 when a test fails; a test, or a file's top level, that runs past --timeout-secs (30) fails and its plugin is stopped. A folder with no plugin.toml, a plugin that isn't a Lua plugin or one with no test files is refused.