Worked examples

24 worked examples with real files, one per extension surface. Each states what was checked.

Start withPrompt section overridesReplacing a built-inIntercept points

Plugins

Your first plugin

What kcode plugins scaffold gives you: a manifest, a tool, an event hook, and durable storage.

~/.kcode/plugins/hello/

Checked with kcode plugins validate before publishing.

plugin.toml
name = "hello"
version = "0.1.0"
description = "What kcode plugins scaffold gives you: a tool, a hook, durable storage"
kind = "Lua"

[capabilities]
kv = true
hooks = true
main.lua
-- Runs when the plugin loads. Everything registered here joins the session.
kcode.register_tool("hello", "Say hello and count how often you did", function(args)
  local name = args.name or "world"
  local count = tonumber(kcode.kv_get("greetings") or "0") + 1
  kcode.kv_set("greetings", tostring(count))
  return { text = "Hello, " .. name .. "! Greeting number " .. count }
end, {
  -- The schema tells the model which arguments it can pass.
  schema = {
    type = "object",
    properties = { name = { type = "string", description = "Who to greet" } },
  },
})

kcode.on_event("core.app.turn-finished", function(ev)
  kcode.log("turn finished (" .. ev.kind .. ")")
end)
commands/hello.md
---
description: Greet the current project by name
---
Use the `hello` tool with the name of the project in the working directory,
then reply with one line.
skills/hello.md
---
name: hello
description: How to greet politely
---
When asked to greet someone, use the `hello` tool once and keep the reply to a single line.
Lua host API · register_tool

A tool in Lua

Give the agent a new tool. It shows up in the registry like a built-in and asks for permission the same way.

~/.kcode/plugins/todo-count/

Checked with kcode plugins validate before publishing.

plugin.toml
name = "todo-count"
version = "0.1.0"
description = "A tool the agent can call: count TODO lines in the project's notes"
kind = "Lua"

[capabilities]
"fs.read" = ["**/*.md", "**/*.txt"]
main.lua
-- The handler receives the arguments the model passed and returns a table; the schema at the
-- end tells the model which arguments there are.
-- fs_list takes an optional folder and returns a { path, is_dir } row for everything under it,
-- subfolders included; it and fs_read only see the files inside the globs granted under
-- [capabilities]. fs_read raises an error for a file it can't read, such as one that isn't
-- UTF-8 text, so pcall skips those.
kcode.register_tool("todo_count", "Count TODO lines in the project's notes", function(args)
  local marker = args.marker or "TODO"
  local total, files, lines = 0, 0, {}
  for _, entry in ipairs(kcode.fs_list(args.prefix)) do
    if not entry.is_dir then
      local ok, text = pcall(kcode.fs_read, entry.path)
      if ok then
        files = files + 1
        for line in text:gmatch("[^\n]+") do
          if line:find(marker, 1, true) then
            total = total + 1
            if #lines < 50 then lines[#lines + 1] = entry.path .. ": " .. line end
          end
        end
      end
    end
  end
  return { count = total, files = files, marker = marker, lines = lines }
end, {
  schema = {
    type = "object",
    properties = {
      marker = { type = "string", description = "The text to count; TODO when left out" },
      prefix = { type = "string", description = "The folder to search; all granted files when left out" },
    },
  },
})
Lua host API · register_command

A command

A slash command that runs your code instead of a prompt.

~/.kcode/plugins/branch-note/

Checked with kcode plugins validate before publishing.

plugin.toml
name = "branch-note"
version = "0.1.0"
description = "A slash command backed by code instead of a prompt"
kind = "Lua"

[capabilities]
kv = true
main.lua
-- /branch-note <text>: the handler gets everything after the command name
-- and returns markdown, which kcode renders in the transcript.
kcode.register_command("branch-note", "Keep a note for this branch", function(text)
  if text == nil or text == "" then
    local saved = kcode.kv_get("note")
    if saved then return "**Branch note:** " .. saved end
    return "No note yet. Try `/branch-note remember to squash before merging`."
  end
  kcode.kv_set("note", text)
  return "Saved: _" .. text .. "_"
end)
Lua host API · on_event

Listening to events

React to the loop: file changes, timer ticks, turn boundaries.

~/.kcode/plugins/turn-log/

Checked with kcode plugins validate before publishing.

plugin.toml
name = "turn-log"
version = "0.1.0"
description = "React to what the loop does: files, timers, turn boundaries"
kind = "Lua"

[capabilities]
hooks = true
notify = true
main.lua
-- Every handler gets {kind, source, intent, data}; data holds the event's
-- own fields, listed for each event under Reference › Events and hooks.
kcode.on_event("core.fs.change", function(ev)
  -- The project watcher, gitignore-filtered.
  kcode.log("changed: " .. tostring(ev.data.path))
end)

kcode.on_event("core.app.turn-started", function(ev)
  kcode.log("turn started from " .. tostring(ev.source))
end)

kcode.on_event("core.app.turn-error", function(ev)
  kcode.notify("kcode turn failed", tostring(ev.data.summary))
end)
Triggers · [[triggers.cron]] · [[triggers.every]]

Cron and every

Schedules declared in the manifest fire core.timer.tick with your entry name, once for the app or per project or session.

~/.kcode/plugins/heartbeat/

Checked with kcode plugins validate before publishing.

plugin.toml
name = "heartbeat"
version = "0.1.0"
description = "Schedules declared in the manifest; each fires core.timer.tick with its name"
kind = "Lua"

[capabilities]
hooks = true
notify = true

# A schedule fires once for the whole app, not once in every open session.
# fires_per = "project" fires it in each open project; "session" in every session.

# Six fields, seconds first, in local time: every weekday at 09:00 on your clock.
[[triggers.cron]]
name = "standup"
schedule = "0 0 9 * * 1-5"

# A plain period: 30s, 5m, 2h.
[[triggers.every]]
name = "pulse"
period = "5m"
main.lua
-- One event kind for every schedule; the entry's name tells them apart.
kcode.on_event("core.timer.tick", function(ev)
  if ev.data.name == "standup" then
    kcode.notify("Standup", "Time to write the daily note")
  elseif ev.data.name == "pulse" then
    kcode.log("still here")
  end
end)

-- The same schedule can be registered from code instead of the manifest:
-- weekdays at 18:00 local time, once for the app, like a manifest schedule.
-- A third argument, { fires_per = "project" } or { fires_per = "session" }, changes that.
kcode.on_cron("0 0 18 * * 1-5", function()
  kcode.notify("Wrap up", "Commit what you have before you leave")
end)
Lua host API · on_input

Rewriting input

Expand shorthand or veto a prompt before the turn starts.

~/.kcode/plugins/shorthand/

Checked with kcode plugins validate before publishing.

plugin.toml
name = "shorthand"
version = "0.1.0"
description = "Rewrite or veto the prompt before the turn starts"
kind = "Lua"

[capabilities]
"input-transform" = true
main.lua
-- Return nil to pass the text through, a string or {text=} to rewrite it,
-- or {veto="reason"} to stop the turn. Vetoes show in chat, attributed to the plugin.
local expansions = {
  ["#t"] = "Run the test suite and fix every failure you find.",
  ["#r"] = "Review the working diff and list findings by severity.",
}

kcode.on_input(function(input)
  local expanded = expansions[input.text]
  if expanded then return { text = expanded } end
  if input.text:find("DROP TABLE", 1, true) then
    return { veto = "This plugin refuses prompts that mention dropping tables." }
  end
  return nil
end)
Lua host API · intercept · core.shell.pre

Gating shell commands

A blocking check before every shell command, whichever tool runs it. Return nothing to allow, or a reason to block.

~/.kcode/plugins/no-force-push/

Checked with kcode plugins validate before publishing.

plugin.toml
name = "no-force-push"
version = "0.1.0"
description = "A blocking check before every shell command"
kind = "Lua"

[capabilities]
hooks = true
main.lua
-- core.shell.pre hands over the command bash, shell_spawn or shell_proceed
-- is about to run, so one check covers every way the agent runs a command.
-- Return nil to allow, or {veto="reason"} to block. The check fails open on
-- error or timeout; the session permission engine remains the boundary.
kcode.intercept("core.shell.pre", function(run)
  local cmd = run.command
  if cmd:find("push%s+.*%-%-force") or cmd:find("push%s+%-f") then
    return { veto = "Force pushes are blocked by the no-force-push plugin." }
  end
  return nil
end)
Lua host API · run_tool · spawn_subagent · inject

Driving the agent

Run tools, start subagents, and wake the session from plugin code.

~/.kcode/plugins/nightly-review/

Checked with kcode plugins validate before publishing.

plugin.toml
name = "nightly-review"
version = "0.1.0"
description = "Run tools, start subagents, and wake the session from plugin code"
kind = "Lua"

[capabilities]
hooks = true
"run-tool" = true
"spawn-subagent" = true
inject = true

# A review of the project: once in each open project, at 02:00 UTC.
[[triggers.cron]]
name = "nightly"
schedule = "0 0 2 * * *"
fires_per = "project"
main.lua
kcode.on_event("core.timer.tick", function(ev)
  if ev.data.name ~= "nightly" then return end

  -- run_tool goes through the permission engine with this plugin as the caller.
  -- It returns the tool's structured result, the same value the model sees:
  -- for bash, a table with exit_code, stdout and stderr.
  local status = kcode.run_tool("bash", { command = "git status --short | wc -l" })
  kcode.log("dirty files: " .. status.structured.stdout:gsub("%s", ""))

  -- spawn_subagent returns {name=} at once. Its finish wakes the session as a
  -- <cp:subagent> notice, and plugins hear it as core.app.subagent-finished.
  local child = kcode.spawn_subagent({
    prompt = "Review yesterday's commits for anything risky. Report, do not change files.",
    kind = "security-reviewer",
    name = "nightly",
  })

  -- inject wakes the session with an agent-visible note.
  kcode.inject("Nightly review started as " .. child.name
    .. ". Summarise its findings when it finishes.")
end)
Manifest · shadows · replace-builtin

Replacing a built-in

Shadow a built-in tool by name. Safety-critical names need the grant and project trust.

<project>/.kcode/plugins/safe-bash/

Checked with kcode plugins validate before publishing.

plugin.toml
name = "safe-bash"
version = "0.1.0"
description = "Shadow a built-in; safety-critical names need the grant and project trust"
kind = "Lua"

# The plugin's `bash` replaces the built-in for this session.
shadows = ["bash"]

[capabilities]
"replace-builtin" = true
"run-tool" = true
main.lua
-- A wrapper that refuses a few commands and forwards the rest to the real tool.
-- Inside this plugin "bash" is the wrapper itself; the original is "builtin:bash".
-- shell_spawn and shell_proceed still run commands; gate those at core.shell.pre.
local refused = { "rm -rf /", "mkfs", ":(){ :|:& };:" }

kcode.register_tool("bash", "Run a shell command (guarded)", function(args)
  local cmd = tostring(args.command or "")
  for _, bad in ipairs(refused) do
    if cmd:find(bad, 1, true) then
      return { error = "safe-bash refused: " .. bad }
    end
  end
  return kcode.run_tool("builtin:bash", args)
end, {
  schema = {
    type = "object",
    properties = { command = { type = "string", description = "The command to run" } },
    required = { "command" },
  },
})
Lua host API · intercept

Intercept points

Pass, veto, or rewrite at core.* points: provider requests, compaction, continuation.

~/.kcode/plugins/guardrails/

Checked with kcode plugins validate before publishing.

plugin.toml
name = "guardrails"
version = "0.1.0"
description = "Pass, veto, or rewrite at the core.* intercept points"
kind = "Lua"

[capabilities]
hooks = true
main.lua
-- Each handler returns nil (pass), {veto="reason"}, or {rewrite=<payload>}.

-- Before a request leaves for the provider: cap the reply size. A ChatGPT
-- sign-in sends only the effort and the tools; kcode names a change it
-- can't send once in the plugin's Activity.
kcode.intercept("core.provider.request", function(req)
  if req.max_tokens and req.max_tokens > 8000 then
    req.max_tokens = 8000
    return { rewrite = req }
  end
  return nil
end)

-- Before a compaction pass. A veto puts the pass off. kcode still compacts
-- before the window overflows, so a plugin cannot block it for good.
kcode.intercept("core.compaction.gate", function(gate)
  if gate.before_messages < 20 then
    return { veto = "guardrails: too little history to be worth a summary" }
  end
  return nil
end)

-- When the loop decides whether to go on after a round.
kcode.intercept("core.continuation.decide", function(decision)
  if decision.round > 40 then
    return { veto = "guardrails: 40 rounds is enough for one turn" }
  end
  return nil
end)

-- After a tool errors: add a hint to the text the model reads.
kcode.intercept("core.tool.error", function(err)
  if err.tool == "bash" then
    err.content = err.content .. "\nHint: run it again with `set -x` to see where it fails."
    return { rewrite = err }
  end
  return nil
end)
Manifest · [settings.<key>]

Plugin settings

Declare typed settings; users set them under [plugins.] in config.toml.

~/.kcode/plugins/journal/

Checked with kcode plugins validate before publishing.

plugin.toml
name = "journal"
version = "0.1.0"
description = "Typed settings declared by the plugin, set by the user in config.toml"
kind = "Lua"

[capabilities]
hooks = true
kv = true

[settings.folder]
type = "string"
default = "notes"
description = "Directory the journal is written to, relative to the project"

[settings.max_entries]
type = "integer"
default = 200
description = "Entries to keep before the oldest are dropped"

[settings.tone]
type = "enum"
options = ["plain", "cheerful"]
default = "plain"
description = "How the summaries read"
main.lua
-- Values come from [plugins.journal] in config.toml, falling back to the defaults above.
local folder = kcode.settings.get("folder")
local limit = kcode.settings.get("max_entries")
local tone = kcode.settings.get("tone")

kcode.on_event("core.app.turn-finished", function(ev)
  local entries = tonumber(kcode.kv_get("entries") or "0") + 1
  if entries > limit then entries = limit end
  kcode.kv_set("entries", tostring(entries))
  kcode.log(string.format("journal: %s/%d entries (%s)", folder, entries, tone))
end)
config.toml
# ~/.kcode/config.toml — the user's side of the same settings
[plugins.journal]
folder = "docs/journal"
max_entries = 50
tone = "cheerful"
Capabilities · net.http · fs.read

Network and files

Grants: web access for a plugin, private hosts only by name, and the paths it may read.

~/.kcode/plugins/ci-status/

Checked with kcode plugins validate before publishing.

plugin.toml
name = "ci-status"
version = "0.1.0"
description = "Grants: web access for a plugin, and the paths it may read"
kind = "Lua"

[capabilities]
"net.http" = []
"fs.read" = [
  ".github/workflows/*.yml",
  ".github/workflows/*.yaml",
]
notify = true
main.lua
-- kcode makes the GET for the plugin. With "net.http" = [] it reaches public
-- hosts; localhost and private addresses only when the list names them.
kcode.register_tool("ci_status", "Latest workflow run status of a GitHub repo", function(args)
  local repo = args.repo
  local url = "https://api.github.com/repos/" .. repo .. "/actions/runs?per_page=1"
  local res = kcode.fetch(url)
  if res.status ~= 200 then
    return { error = "GitHub answered " .. res.status }
  end
  local conclusion = res.body:match('"conclusion"%s*:%s*"([%w_]+)"') or "unknown"
  return { repo = repo, conclusion = conclusion }
end, {
  schema = {
    type = "object",
    properties = { repo = { type = "string", description = "owner/name, such as actions/checkout" } },
    required = { "repo" },
  },
})

-- fs_list takes a folder and only sees paths inside the granted globs.
kcode.register_tool("workflows", "List the workflow files in this repo", function()
  local files = {}
  for _, entry in ipairs(kcode.fs_list(".github/workflows")) do
    files[#files + 1] = entry.path
  end
  return { files = files }
end)
Plugin runtimes · MCP

MCP servers

Claude-Code-compatible .mcp.json; each server's tools register as __.

<project>/.mcp.json

Syntax-checked before publishing; not run through kcode plugin validation.

.mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/code/app"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}
README.txt
Put .mcp.json at the project root (or ~/.kcode/mcp.json for every project).
Each server's tools register as <server>__<tool>, so the filesystem server's
read_file becomes filesystem__read_file in /tools and in the permission prompt.
Model vendors accept only letters, digits, _ and - in a tool name, so kcode
replaces any other character with _.

Every server connects when the session spawns: stdio, HTTP and SSE. A server
that can't connect is named in the chat, and /mcp and /plugins list it under
Not connected, with the error, until it connects. From the shell:

  kcode mcp list
  kcode mcp add --transport sse docs https://mcp.example.com/sse
  kcode mcp reconnect github --session "release"

An untrusted project contributes no .mcp.json at all.
Plugin runtimes · Content

A content bundle

No code: commands, skills, agents, output styles, and themes in one directory.

~/.kcode/plugins/house-style/

Checked with kcode plugins validate before publishing.

plugin.toml
name = "house-style"
version = "0.1.0"
description = "No code: commands, skills, agents, output styles, and themes in one bundle"
kind = "Content"
agents/docs-writer.md
---
name: docs-writer
description: Writes and edits documentation only
tools: [fs_read, fs_write, fs_edit, grep]
---
You write documentation. Keep sentences short.
Never edit files outside docs/.
commands/standup.md
---
description: Write today's standup note from the git log
---
Read the commits since yesterday morning and write a three-line standup note:
done, doing, blocked.
output-styles/brief.md
---
name: brief
description: Three sentences, then stop
---
Answer in at most three sentences. Prefer a command or a file path over an explanation.
skills/changelog.md
---
name: changelog
description: How this team writes changelog entries
---
One line per change, present tense, user-facing wording, no ticket numbers in the text.
themes/ember.ron
(
  extends: "kcode",
  colors: (
    background: (dark: "#0b0806", light: "#fff8ef"),
  ),
  type_scale: (mono: (size: 13.0)),
)
Project config · [[hooks]]

Project hooks

Automation without a plugin: on a file change, a schedule, or a turn boundary, run a skill or inject a prompt. Hooks run once you turn on Project hooks in Settings (hooks_enabled).

<project>/.kcode/config.toml

Syntax-checked before publishing; not run through kcode plugin validation.

config.toml
# <project>/.kcode/config.toml
# Hooks run once you turn on Project hooks in Settings › Advanced,
# or set hooks_enabled = true in ~/.kcode/config.toml.
# on: fs:file-changed · timer:cron · app:turn-finished
#     worktree:create · webhook:<name>
#
# Each hook is held to its own rate limits, counting only the fires it
# matches. They are set under [triggers_framework.rate_limits] in
# ~/.kcode/config.toml and take effect when kcode restarts:
#   per_minute = 60               # fires a minute, any hook
#   per_turn = 50                 # fires since a turn last started in the project,
#                                 # for a hook that runs a prompt or a command
#   start_new_cooldown_secs = 30  # the least gap between fires of such a hook
# A timer hook whose schedule breaks a limit is skipped with a notice. A fire
# a limit drops adds one notice naming the hook and the limit, which counts
# the drops that follow.

[[hooks]]
name = "retest"
on = "fs:file-changed"
filter = "src/**/*.rs"
prompt = "A source file changed. Run its tests and report failures."
concurrency = "replace"   # drop | queue | replace | parallel

[[hooks]]
name = "morning-triage"
on = "timer:cron"
schedule = "0 0 9 * * 1-5"
run = "/triage"           # skills/triage/SKILL.md, beside this file
session = "title:triage"  # active | new | title:<t>

[[hooks]]
name = "after-turn"
on = "app:turn-finished"
prompt = "If you changed files this turn, run the formatter."
enabled = true
skills/triage/SKILL.md
---
name: triage
description: >-
  Morning triage: what changed since yesterday, what fails, and
  what to pick up first.
---

# Morning triage

1. Run `git log --since=yesterday --oneline` and sum up the changes.
2. Run the project's tests and list each failure with its file.
3. Search for TODO and FIXME lines added since yesterday.
4. End with the three things to pick up first, most urgent first.

Report only: change no files.
CLI · kcode trigger · [[hooks]] webhook

Webhooks and kcode trigger

Fire a turn from CI or cron, and POST a fire record to any URL. The hooks need Project hooks on in Settings (hooks_enabled).

<project>/.kcode/config.toml

Syntax-checked before publishing; not run through kcode plugin validation.

ci.sh
#!/usr/bin/env bash
# From CI, cron, or a shell: wake the session with a named trigger and some text.
# The deploy-done hook in config.toml runs with the text in its {{text}}, in the
# session --session names. It runs only with hooks_enabled = true in
# ~/.kcode/config.toml (Settings › Advanced › Project hooks). Until then, or with
# no open session titled "release", the trigger runs nothing, says why, and exits 1.
kcode trigger deploy-done "Build 812 is live on staging" \
  --project ~/code/app \
  --session "release"
config.toml
# <project>/.kcode/config.toml
# Hooks run once you turn on Project hooks in Settings › Advanced,
# or set hooks_enabled = true in ~/.kcode/config.toml.
[[hooks]]
name = "deploy-done"
on = "webhook:deploy-done"
prompt = "A deploy finished: {{text}}. Check the health endpoint and summarise the release."
session = "title:release"

# Also POST a fire record to an external URL when this hook runs.
[[hooks]]
name = "notify-chat"
on = "app:turn-finished"
webhook = "https://hooks.example.com/kcode"
System prompt · ~/.kcode/prompt/

Prompt section overrides

Replace one section of the system prompt with your own markdown. No recompile.

~/.kcode/prompt/style.md

No automated check is configured for this example.

README.txt
Drop a markdown file in ~/.kcode/prompt/ named after the section it replaces:

  identity.md   tools.md   style.md   rich-output.md
  memory.md     recall.md  control-plane.md

The file replaces that section of the built-in system prompt at the next session
start. Remove it to get the default back. No rebuild, no plugin.
style.md
Answer in simple English. Keep it brief. No filler.
When you are unsure, say what you checked and what you did not.
Prefer a command or a file path over a paragraph.
Themes · extends

A theme

Start from a bundled theme and change only the leaves you want.

~/.kcode/themes/ember.ron

No automated check is configured for this example.

ember.ron
(
  extends: "kcode",
  colors: (
    background: (dark: "#0b0806", light: "#fff8ef"),
  ),
  type_scale: (mono: (size: 13.0)),
)
README.txt
Save as ~/.kcode/themes/ember.ron (JSON works too), then /theme ember.
`extends` starts from a bundled theme; you override only the leaves you name.
`kcode` follows the light/dark mode, so a (dark: …, light: …) pair picks the
mode's value. kcode-dark, kcode-light and kcode-high-contrast keep one mode, and
a pair over one of them takes that mode's value. The token contract is on the
Themes reference page.
Config · [keymap]

Rebinding keys

Every app shortcut is data. Rebind, add a second chord, or unbind.

~/.kcode/config.toml

Syntax-checked before publishing; not run through kcode plugin validation.

config.toml
# ~/.kcode/config.toml — every app chord is data.
[keymap]
new_session = "cmd-shift-n"                   # rebind
command_palette = ["cmd-p", "cmd-shift-p"]    # two chords
mission_control = "cmd-shift-m"
notifications = false                         # unbind
Project config · policy.toml

Project policy

Block named plugins and warn when a required plugin is not loaded.

<project>/.kcode/policy.toml

Syntax-checked before publishing; not run through kcode plugin validation.

policy.toml
# <project>/.kcode/policy.toml — committed with the repo.
[plugins]
# Refused in this project's sessions on every load path, with their bundled commands,
# skills, agents and output styles. Themes are the window's, so a user plugin's theme stays.
blocklist = ["safe-bash", "shorthand"]
# Each session and /plugins warn when one of these isn't loaded.
required = ["no-force-push"]
Config · KCODE_* · --config

Config layering

Compiled defaults, user config, trusted project config, an optional launch profile, environment variables, then command-line flags.

shell

Syntax-checked before publishing; not run through kcode plugin validation.

config.toml
# Layers, lowest first:
#   built-in defaults
#   ~/.kcode/config.toml            (this file)
#   <project>/.kcode/config.toml
#   --config <path>                 (one launch)
#   KCODE_* environment variables
#   command-line flags
default_model = "claude-sonnet-5"
default_effort = "medium"

[session_presenter]
ui_scale = 110
env.sh
# Environment variables map to keys; a double underscore descends into a table.
export KCODE_DEFAULT_MODEL="claude-opus-5"
export KCODE_SESSION_PRESENTER__ANIMATION_FPS=60

# A launch profile on top of user + project config, for one run:
kcode --config ./profiles/ci.toml

# Print the whole surface with defaults, to see what a key is called:
kcode config defaults
CLI · kcode -p

Headless with ndjson

One prompt, one process, one JSON line per event. Built for scripts and CI.

shell

No automated check is configured for this example.

functions.json
{
  "type": "object",
  "required": ["functions"],
  "properties": {
    "functions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name", "line"],
        "properties": {
          "name": { "type": "string" },
          "line": { "type": "integer" },
          "doc": { "type": "string" }
        }
      }
    }
  }
}
run.sh
# One prompt, one process. text | json | ndjson.
kcode -p "List the failing tests and the file each one lives in" \
  --output-format ndjson \
  --permission-mode plan

# Constrain the reply to a JSON schema.
kcode -p "Extract the public functions in src/lib.rs" \
  --output-format json \
  --json-schema ./schemas/functions.json

# Continue the most recent session without the window.
kcode -c --print
Config · curated keys

Settings that change behavior

The handful of keys that change how kcode looks, asks, remembers, and updates.

~/.kcode/config.toml

Syntax-checked before publishing; not run through kcode plugin validation.

config.toml
# ~/.kcode/config.toml: the keys that change how kcode looks, asks,
# remembers, and updates.
theme = "kcode-dark"
default_output_style = "terse"
default_effort = "high"

[session_presenter]
ui_scale = 110
default_layout = "Grid"

[session_presenter.shader]
backdrop = "shader"
background = "dot-matrix"
wordmark = "kcode"
reactive = true
per_tile = false

[compaction]
auto_compact_tokens = 120000

[memory]
auto_recall = true

[memory_consolidator]
enabled = true

[subagent]
advisor_model = "gpt-5.5"

[updater]
automatic = true

[session_daemon]
keep_awake = true
CLI · kcode plugins validate

Validate plugins

The same checks a session load runs, as a command you can put in CI.

shell

No automated check is configured for this example.

ship.sh
# The same checks a session load runs: manifest shape, capability keys, the
# retired flat `permissions` list, an entry point that loads.
kcode plugins validate ~/.kcode/plugins/nightly-review

# Project-scoped plugins travel with the repo; validate them in CI.
for dir in .kcode/plugins/*/; do
  kcode plugins validate "$dir" || exit 1
done

# See what a session actually loaded, and each plugin's grants.
#   /plugins