Headless

Run kcode from a script or CI with one prompt and structured output.

One prompt, one process

kcode -p "Summarise the failing tests in this repo" --output-format text

-p runs a single turn in the current directory without the window and prints the reply. --output-format is text, json, or ndjson:

  • text prints the final reply.
  • json prints one object with the reply and the run’s metadata.
  • ndjson prints one JSON line per event as the turn runs, which is what a script should parse.

Add --json-schema <file> to make the reply conform to a schema.

Permissions

A headless run has no one to answer the ask dialog, so a tool call that needs permission is refused, unless one of your allow rules covers it. A new session starts in auto unless permissions.default_mode names another mode. --permission-mode picks the mode for one run:

kcode -p "Summarise the open TODOs" --permission-mode plan

plan reads only: no writes, and no shell command except one that only reads. default needs permission for a write or a shell command that does more than read. accept-edits writes project files without asking, but a write outside the project or a shell command that does more than read needs permission. auto runs every call without asking, except a call that reads or writes a secret location (permissions.secret_paths); --bypass-permissions is the same as --permission-mode auto. Deny rules apply in every mode. Untrusted projects contribute no .kcode config and no .mcp.json, headless or not. To trust one without the app, run kcode trust in it (or kcode trust <folder>): it lists what the project holds and asks, and --yes skips the question in a script.

A launch profile

kcode -p "..." --config ./ci.toml

--config layers one more file on top of the user and project config for this launch. Environment variables layer on top of that: KCODE_DEFAULT_MODEL=... sets default_model; nested keys use a double underscore, as in KCODE_SESSION_PRESENTER__ANIMATION_FPS=60.

Wake a running session

kcode trigger deploy-done "Build 812 is live" --project ~/code/app --session "release"

kcode trigger sends text into a session as an external trigger event. Pair it with a [[hooks]] entry whose on = "webhook:deploy-done" to run a skill or a prompt instead; the hook gets the text, in place of {{text}} in its prompt (or after a prompt without it), or as its skill’s arguments. Hooks run once you turn on Project hooks in Settings (hooks_enabled). --session names the session the trigger runs in, its hooks included, and fails when no open session has that title. While a project’s hooks for the trigger cannot run (hooks are off, the project is not trusted, or no session is open where they run) the trigger runs nothing and says why. kcode trigger exits 1 whenever the trigger ran nothing, so a CI step fails instead of passing quietly. The Extensibility page shows both halves.

Resume

kcode -p "Now add the tests" --resume <id>
kcode -p "And update the changelog" -c

With --resume <id>, the prompt runs as that session’s next turn: it sees the session’s history and runs in its folder, on its model and settings. -c continues the session created most recently. --model becomes the session’s model, so a later -c keeps it.

A session open in the kcode app, or in use by another kcode -p run, is refused until it is let go. Without -p, kcode --resume <id> opens the session in the app, and --print prints its transcript instead.