What kcode does
kcode runs many agents at once, with a prompt, tools and loop that are yours to change.
Many agents, one window.
kcode puts every session from every project in one window, each one a live tile.
- Opens a session with a click on its tile, and gives it the whole window with a second click
- Finds any project or session by name, and any command by what it does
- Sends a notification when an agent fails or waits for input, with a macOS banner when another app is in front

A second opinion from a different model.
kcode can consult an advisor on a second model before a step that is hard to undo, or between two approaches. kcode gives the advisor its own read of the code, so the advice is independent and not an echo of the agent.
- Keeps the advisor read-only.
- Runs the advisor on the model you pick, and refuses the agent's own, since the same model gives no second opinion
- Also has agents for planning, research and security review, and loads your own agent from one Markdown file
- Can start a full session on its own branch and port, and lets agents message each other while they work
---
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/.Sessions that run on a goal or a schedule.
kcode keeps a session working toward its goal until the agent reports it done or blocked, and starts scheduled work on time.
- Repeats an instruction on a timer or when a session goes quiet, and lets the agent set its own timers
- Starts a turn from a cron time, a file change, a webhook or your CI
- Stops driving a goal that stalls and sends a notification, so a stuck session does not keep spending turns
- Keeps the Mac from idle sleep while an agent works, so a long job does not stop halfway

A shell that keeps the work moving.
kcode keeps your directory, exports and virtual environment between commands. Long builds keep running in the background, and their output stays available, so the agent can fix errors without rerunning the build.
- Keeps a
cd, an export or an activated virtualenv from one command to the next, as one terminal does - Reads each command before it runs: the program it calls, whether it writes and how many files each pattern matches. In plan mode, kcode runs only the commands that read
- Moves a command that runs past its time limit to the background and wakes the agent when it ends, so a slow build runs once
- Keeps the full output, so the agent can read the last error without running the build again
- Reports the exit code of each stage of a pipe, so failing tests still fail when piped through
tail - Asks for a
sudopassword in its own dialog, so the model never sees it - Lets a plugin rewrite or stop any command, for example to run it in a container
// $ cargo build --release
{
"exit_code": null,
"timed_out": true,
"background_exec_id": "e14",
"notify_on_exit": "armed ...",
"elapsed_ms": 120000,
"stderr": " Compiling shop-api"
}Search by text, meaning and symbol.
kcode helps the agent trace callers and definitions through your language server before an edit, so it can inspect code beyond the files already open.
- Searches by text, and by meaning with an index built on your Mac. kcode never uploads the code to build it
- Gives the agent definitions, references and an outline of the whole project, so it opens the right files first
- Surfaces diagnostics after an edit to help the agent check its work; the project’s compiler and tests still decide whether it passes
Batteries included.
kcode comes with the tools an agent needs for a whole job, built to work together, so there are no MCP servers to set up first. kcode also lets a plugin replace any of them.
- Its own bash, built in
- A test runner that finds your tests, and never counts a run that found none as a pass
- File edits and patches, and code search by text, by meaning and through your language server
- Web search, page fetches, a headless browser with its own profile and none of your cookies, and image reading for screenshots and designs
- A task list for long jobs, timers, notifications, saved memories, and a search of past sessions
- Subagents, sessions on their own worktree, messages between agents, and the advisor

A memory for you, and one for each project.
kcode remembers what it learns about your preferences and each project, from one session to the next.
- Saves the facts worth keeping from past sessions, in a review that runs every few sessions
- Records how sure each memory is and where it came from, and tells the agent when a new fact replaces an old one
- Lets the agent search everything said in a session, including what no longer fits in its context
Skills that run as programs.
kcode runs a skill written in Lua itself, in a sandbox, with only the access the skill declares. kcode checks the input and the result against the shapes the skill promises, so the result of one skill can feed the next.
- Lets this skill read package.json and Cargo.toml and nothing else, and holds back any result whose bump is not major, minor, patch or none
- Sends a skill's own tool calls through the same approvals and plugins as the agent's
- Keeps saved state for each skill between runs, shared by every worktree of the project, and runs one copy of it at a time unless the skill allows more
- Also runs guide skills, the Markdown kind other agents read, and checks their inputs before the agent starts
---
name: next-version
description: Work out the next release version and its
changelog section from Conventional Commit subjects.
entry: run.lua
capabilities:
fs.read: [package.json, Cargo.toml]
input_schema:
type: object
required: [commits]
additionalProperties: false
properties:
commits:
type: array
items: {type: string}
output_schema:
type: object
required: [current, next, bump, changelog]
properties:
current: {type: string, pattern: '^\d+\.\d+\.\d+$'}
next: {type: string, pattern: '^\d+\.\d+\.\d+$'}
bump: {enum: [major, minor, patch, none]}
changelog: {type: string}
---
# Next version
Run this before a release. Pass the commit subjects since
the last tag, from `git log --format=%s <last tag>..HEAD`.
Review the result against the project's versioning rules
before putting `changelog` at the top of CHANGELOG.md,
setting the version to `next` and tagging it. When `bump`
is `none`, the inspected commit subjects do not indicate
a version change.-- next-version: the next semantic version from Conventional Commit subjects.
-- kcode.fs_read reaches only the two files under fs.read in SKILL.md.
local function current_version()
local ok, text = pcall(kcode.fs_read, "package.json")
if ok then return text:match('"version"%s*:%s*"(%d+%.%d+%.%d+)"') end
ok, text = pcall(kcode.fs_read, "Cargo.toml")
if ok then return text:match('\nversion%s*=%s*"(%d+%.%d+%.%d+)"') end
end
local SECTIONS = {
{ key = "breaking", title = "Breaking changes" },
{ key = "feat", title = "Features" },
{ key = "fix", title = "Fixes" },
}
function run(args)
local current = current_version()
if not current then error("no version in package.json or Cargo.toml") end
local major, minor, patch = current:match("(%d+)%.(%d+)%.(%d+)")
major, minor, patch = tonumber(major), tonumber(minor), tonumber(patch)
local found = { breaking = {}, feat = {}, fix = {} }
for _, subject in ipairs(args.commits) do
local kind, rest, text = subject:match("^(%a+)([^:]*):%s*(.+)$")
if kind and rest:sub(-1) == "!" then
table.insert(found.breaking, text)
elseif found[kind] then
table.insert(found[kind], text)
end
end
local bump = (#found.breaking > 0 and "major")
or (#found.feat > 0 and "minor")
or (#found.fix > 0 and "patch")
or "none"
-- Before 1.0.0, a breaking change moves the minor number.
if bump == "major" and major == 0 then bump = "minor" end
local next_version = ({
major = (major + 1) .. ".0.0",
minor = major .. "." .. (minor + 1) .. ".0",
patch = major .. "." .. minor .. "." .. (patch + 1),
none = current,
})[bump]
local lines = { "## " .. next_version }
for _, section in ipairs(SECTIONS) do
if #found[section.key] > 0 then
table.insert(lines, "\n### " .. section.title)
for _, text in ipairs(found[section.key]) do table.insert(lines, "- " .. text) end
end
end
return { current = current, next = next_version, bump = bump, changelog = table.concat(lines, "\n") }
endSkills the agent writes for itself.
kcode can save the method of a job that went well as a skill, which works at once for the agent and as a slash command.
- Saves the skill as a Markdown guide in your folder or the project's, where it can be read, changed or deleted
- Runs a script saved next to the guide through the same shell and checks as any other command
- Leaves program skills to people, since each one declares the access it gets
- Can also compact its own context, switch models for the next turn, set its own goal, and run the commands marked for it, such as the built-in commit
Every setting, on screen or in a file.
kcode has a settings screen with a row for every setting, a search across all of them and a mark on each changed one. kcode keeps the same settings in text files, one for you and one for each project, and applies most of them on save.
- Builds a settings form for each plugin from what the plugin declares, with a switch to turn it off
- Includes a theme designer that recolors every part of the window and saves the result as a new theme
- Can give each worktree session its own port and database, so agents working side by side never share one

Your own prompt, tools and loop.
kcode reads each change from a small file and goes back to its default when the file is removed. kcode needs no fork for any of it, so an update keeps every change.
- Replaces any section of the system prompt, such as the answering style, with one Markdown file
- Runs Lua plugins that add a tool or replace a built-in one, with only the file and network access each manifest grants, and connects MCP servers too
- Lets a plugin change what the model sees in the agent loop, which tools run and when the loop stops, and takes hooks, schedules, key bindings and themes with no code at all

A record of every session, on your Mac.
kcode saves each session to a file on your Mac after every turn, ready to search, share or feed to other tools.
- Exports a session as Markdown to share, or as JSON lines for scripts
- Shows a timeline of what the agent was told and when, and a debug view of what a session is waiting on
The full reference.
Every command, setting, shortcut, tool, and event, generated from the app.