Skip to main content
Every Kode task follows the same spine: build a surgical context graph, generate structured JSON hunks via an LLM, pass each hunk through a chain of verification gates, and write only what passes. By the end of this guide you will have initialized a project, run your first task, and read the verification stats that prove what changed — and why.

​
Prerequisites

  • Kode installed and available on your PATH (kode --version should print a version string)
  • A code project inside a git repository (Kode reads and writes files relative to the repo root)
  • Your API key exported as KODE_LLM_API_KEY or OPENAI_API_KEY

​
Steps

​
Understanding gate failures

When a hunk fails verification, the log entry records the gate name and a short message. Use kode explain <check> to get a full description of that gate, its common causes, and suggested fixes:
Each explain command also prints up to five recent examples pulled from logs/kode.log so you can see which files triggered the gate in your own project.
If the same gate fails repeatedly for a specific file, inspect it with kode plan --graph "<task>" to see the full dependency graph for that area of the codebase. Understanding what the context graph captures (and what it omits) often reveals why the LLM is generating incorrect hunks.
kode run is a shortcut for kode generate --apply. It generates patches and immediately applies verified ones, but it does not run your test suite after applying. Use kode loop when you want the full Plan → Generate → Verify → Apply → Test pipeline with automatic rollback on test failure.

​
Next steps

Loop Mode

Run the full pipeline with test execution and automatic rollback — including Ghost Branch parallel strategies.

Verify CLI

Run the verification gate directly against a JSON hunk file or a set of proposed file contents.