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. Pick a posture up front:

kcode -p "Fix the lint errors" --permission-mode accept-edits

plan reads only. accept-edits allows writes and execution but still honours deny rules. bypass allows everything; use it in a sandbox. Untrusted projects contribute no .kcode config and no .mcp.json, headless or not.

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__GRID_MAX=6.

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 inject a prompt when it fires. The Extensibility page shows both halves.

Resume

kcode --resume <id> picks a session up where it left off; -c resumes the most recent one. Both work with --print for a non-interactive continuation.