Home > FAQs > Katas

What is a kata in OpenCues?

A kata is a guided, in-editor scenario: an ordered lesson you work through in your real editor ("enter plan mode, ask for a plan, switch model, commit to git") while a live coach in the secondary display tells you the next micro-action, corrects you when you drift, and detects your progress from what you type and press. You never announce completion; you just do the thing. Katas run on all five hosts, and the KATA.md file format is part of the open standard.

Starting, stopping, advancing

start kata 1 _ starts by id; start kata git-basics _ by name; a bare start kata _ starts the first installed kata. An unknown id shows the installed catalogue in the secondary display.
stop kata _ exits, always, with no model involved.
next _ / done _ manually advance past the current step; skip _ force-skips a step you're stuck on.

You rarely need the advance phrases. Progress is detected from your typed text, your submits, and salient key presses (Tab/Shift+Tab, Escape, arrows, Enter), so steps that happen outside the input box, like mode toggles or pickers, complete on their own. On a step the coach can't observe, saying "done" is trusted.

Modal, and guaranteed escapable

Kata mode is modal: while a kata runs, normal LLM behaviour (word cues, fluid and transform blanks, config intent, sentence cues) is suppressed so nothing races the lesson, while local features a kata might teach, like navigation, cycling, and keyword-bound blanks, keep working. Stopping restores everything instantly and nothing is ever written to your settings. The escape ladder starts from the weakest assumption: pressing Escape three times in a row always exits, deterministically, with no API key, no network, and in any language (three presses, not two, so Claude Code's normal double-Esc clear-input can't end a kata by accident). Below that sit stop kata _, a plain "please stop this kata" to the coach, and skip _ for per-step relief.

Write your own: KATA.md

A kata lives at katas/<name>/KATA.md under the normal .cues/ search path, project-level or user-level. The format is small: optional frontmatter (name, id, title, and a next: link that chains katas into a curriculum), then one ## heading per step, with the step body as instruction prose the coach draws on. A file with zero steps is treated as absent.

The file format graduated into the open standard (spec/kata-spec.md, with a JSON Schema and conformance fixtures); the coaching runtime deliberately did not, so another implementation may coach differently, or not at all. Three security floors are normative for any runtime that consumes katas: a kata starts only on explicit user consent, exiting is deterministic and model-independent, and coaching is display-only - it can never write to your buffer, execute anything, or cause side-effects.