Your first plugin

Scaffold a Lua plugin, give the agent a tool, and validate it.

Scaffold

kcode plugins scaffold hello

This writes ~/.kcode/plugins/hello/ with four files:

  • plugin.toml: the manifest. Name, version, kind = "Lua", and a [capabilities] table that says which host APIs the plugin may call.
  • main.lua: the entry point. The scaffold registers a tool, subscribes to an event, and stores a counter in durable storage.
  • commands/hello.md: a slash command whose body is a prompt.
  • skills/hello.md: a skill the agent can read.

Add --project to scaffold into <project>/.kcode/plugins/ instead, so the plugin travels with the repository.

The manifest

name = "hello"
version = "0.1.0"
description = "My first plugin"
kind = "Lua"

[capabilities]
kv = true
hooks = true

kind is required: it says how the plugin runs, and is "Lua", "Mcp" or "Content" (a bundle of commands, skills, agents, output styles or themes with no code). A manifest without it fails to load, and /plugins lists the plugin under Failed to load with the reason; kcode plugins validate catches it first.

Capabilities are grants. kv allows the kcode.kv_* storage functions, hooks allows kcode.on_event. Network access is a grant too: "net.http" = [] lets kcode.fetch reach public hosts, and it reaches a host on your Mac or your private network only when the list names it ("net.http" = ["localhost"]). File reads narrow to globs ("fs.read" = ["**/*.md"]). A call without its grant fails with an error that names the plugin and the exact key to add. Registering tools needs no grant; what a tool does is governed by the session’s permission engine like any other tool call.

A tool

In ~/.kcode/plugins/hello/main.lua, replace the scaffolded tool registration with this one, or add this registration alongside it:

kcode.register_tool("hello_todo_count", "Count lines with a marker in the notes", function(args)
  local marker = args.marker or "TODO"
  local total = 0
  for _, entry in ipairs(kcode.fs_list("notes")) do
    if not entry.is_dir then
      for line in kcode.fs_read(entry.path):gmatch("[^\n]+") do
        if line:find(marker, 1, true) then total = total + 1 end
      end
    end
  end
  return { count = total }
end, {
  schema = {
    type = "object",
    properties = {
      marker = { type = "string", description = "The text to count; TODO when left out" },
    },
  },
})

The tool reads files, so add its grant under [capabilities]: "fs.read" = ["notes/**"]. The handler gets the arguments the model passed and returns a table. The last argument’s schema is a JSON Schema object that names those arguments: the model learns an argument only from it, so a tool registered without a schema is offered as taking none. When a handler reads an argument its schema leaves out, the plugin’s Activity in Settings › Plugins names the tool and the argument. Put read_only = true beside schema for a tool that changes nothing, and the permission engine treats its calls as reads. kcode.fs_list takes an optional folder and returns a { path, is_dir } row for every file and folder under it, subfolders included, so the loop skips the folder rows. It and kcode.fs_read only see the paths inside the manifest’s fs.read globs, and kcode.fs_read raises an error when a read fails. The tool appears in /tools under the plugin’s name, and the permission dialog names the plugin when it asks about a call. Start a tool’s name with the plugin’s, as hello_todo_count does: when two plugins add a tool by the same name, the one loaded first keeps it, and the other loads without it and the session tells you which plugin has the name.

An event

Add the event handler at the top level of the same ~/.kcode/plugins/hello/main.lua file, outside the tool function:

kcode.on_event("core.app.turn-finished", function(ev)
  kcode.log("turn took " .. ev.data.elapsed_ms .. " ms and read " .. ev.data.tokens_input .. " tokens")
end)

kcode.on_event runs the handler each time the event fires, and needs the hooks grant. The handler gets { kind, source, intent, data }, and data holds the event’s own fields. The turn events carry these:

Event data fields
core.app.turn-started session_id, model, agent
core.app.turn-finished session_id, tokens_input, tokens_output, elapsed_ms, agent
core.app.turn-error session_id, summary, agent

summary is the error’s text. agent names the subagent that ran the turn, and is nil for the session’s own agent. The events reference lists the fields of every event.

Validate and load

kcode plugins validate ~/.kcode/plugins/hello

The validator runs the same checks a session load runs: manifest shape, unknown capability keys, the retired flat permissions list, a Lua entry point that loads. Start a session and run /plugins to see the plugin and its grants listed.

To verify hello_todo_count, create notes/todo.md in your project with one line such as TODO: try the plugin. After /plugins lists hello, prompt: “Use hello_todo_count to count TODO lines in notes.” The tool should return a count of 1.

Where next

The worked examples page has a checked example for every surface. Three to read first: replacing a built-in tool, prompt section overrides, and intercept points in the agent loop. The rest cover commands, events, cron, input transforms, tool gates, MCP, content bundles, hooks, themes, and the keymap.