Skip to content

Headless JSON protocol

kora send --json and kora chat --json speak a versioned JSONL protocol: one JSON object per line, v:1. stdout is frames only — chrome stays on stderr, so kora ... --json | jq is safe.

Terminal window
SID=$(kora new)
kora send "$SID" --json "say hi in five words" | jq -c '{type,kind,text}'
kora send "$SID" -y --json "list the files in the project root" # -y auto-approves tool calls

Each invocation emits event frames and exactly one terminal result frame with outcome (done, aborted, error) and exitCode. With -y, tool calls are auto-approved — no approval-requested event appears.

kora chat --json (or kora -r <id> --json to resume) reads request frames from stdin and writes events/responses/results to stdout.

Terminal window
printf '%s\n' \
'{"v":1,"type":"request","id":"r1","op":"prompt","data":{"text":"hello"}}' \
'{"v":1,"type":"request","id":"r2","op":"shutdown"}' \
| kora chat --json | jq -c .type
Type Shape When
request {v,type,id,op,data} stdin → kora
response {v,type,id,ok,data?,error?} immediate ack/error for a request
event {v,type,sessionId,kind,...} streamed turn progress
result {v,type,sessionId,turnId,outcome,error?} terminal frame of a turn
error {v,type,error} malformed input; the loop keeps reading

Event kinds include turn-started, note, step-started, text-delta, reasoning-delta, tool-call, tool-result, step-complete, approval-requested, user-input-requested.

Op data Behaviour
prompt {text} Queue a turn (queues while busy)
command {name} Run a local command
continue {} Continue the session
steer {text} Inject steering text mid-turn
cancel {} Abort the in-flight turn → result{aborted}
approve {id, decision} allow / always / deny a pending tool call
answer {id, value} Answer a pending user-input request
shutdown {} Finish the active turn, then exit

approve and answer correlate by data.id = the toolCallId field of the matching approval-requested / user-input-requested event.

shutdown cancels a turn in flight, waits for its terminal result{aborted}, replies ok:false "request dropped by shutdown" to each queued request, then exits. A turn never ends without a result frame. EOF on stdin during an approval/input wait unblocks the turn.

  • Only response frames, no events/result → all requests fired before stdin closed and shutdown raced the queue; upgrade — fixed in the current build, which drains before exiting.
  • result never arrives, session shows running → the provider stream can stall without a deadline; check the session’s .status.json, kill the process if the PID is stale — the lock self-heals.
  • approval-requested blocks forever → nothing approved it. Send {"op":"approve","data":{"id":"<toolCallId>","decision":"deny"}}, or EOF to unblock.
  • Mixed --dev/default profile → the session id lives in the other profile’s sessions/ dir; keep one profile per pipeline.