Skip to main content

Documentation Index

Fetch the complete documentation index at: https://kode-f177b001.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

kode run is the fastest path from a plain-English task to working, verified code on disk. It sends your prompt to the configured LLM, parses the response into structured JSON hunks, runs every hunk through the 6-gate verification pipeline, and writes passing patches directly to your files — all in a single command. Think of it as kode generate --apply with a shorter name.

​
Synopsis

kode run <prompt>

​
What it does

  1. Sends your prompt (plus any context file you provide) to the LLM.
  2. Parses the response into structured hunks — each hunk is a targeted old → new replacement scoped to a single file.
  3. Runs each hunk through the verification pipeline (syntax, imports, call graph, blast radius, architecture, security).
  4. Applies hunks that pass all gates to disk. Hunks that fail are logged with the reason.
  5. Prints a JSON summary to stdout with the list of applied and failed hunks, round count, and duration.
kode run does not execute your test suite. Patches are verified structurally but tests are not run. For full test execution and automatic rollback on failure, use kode loop.

​
Flags

​
--model
string
Override the LLM model for this run. Accepts provider/model format. When omitted, Kode uses the model field from .kode/kode.json, falling back to the KODE_LLM_MODEL environment variable, and finally gpt-4o.
kode run --model openai/gpt-4o "refactor the auth module"
​
--context-file
string
Path to a context packet JSON file produced by kode plan --packet. Providing a context file gives the LLM a surgical, token-capped view of the relevant files and symbols instead of an unfiltered codebase dump.
kode run --context-file context.json "add pagination to the user list"
​
--project-dir
string
default:"cwd"
Project root directory. Kode resolves all file paths relative to this directory. Defaults to the current working directory.

​
Examples

# Simplest form: generate and apply in one shot
kode run "add rate limiting to the API handler"

# Use a specific model
kode run --model openai/gpt-4o "refactor the auth module"

# Provide a pre-built context packet for complex tasks
kode run --context-file context.json "add pagination to the user list"

# Point at a specific project directory
kode run --project-dir ./services/api "extract user validation into a service"
For complex, multi-file tasks, run kode plan --packet "your task" > context.json first. This gives Kode a surgical context graph scoped to the task rather than sending the entire codebase to the LLM, which reduces token cost and improves patch quality.

​
Output

On success, kode run prints a JSON summary to stdout: 
{
  "task_id": "add rate limiting to the API handler",
  "status": "PASS",
  "applied_hunks": ["internal/api/handler.go"],
  "failed_hunks": {},
  "rounds_used": 1
}
If one or more hunks fail verification, the command exits with code 1 and the summary lists each failure with the gate name and reason.

​
Environment variables

VariableDescription
KODE_LLM_API_KEYAPI key for the LLM provider (required if not set in provider config)
OPENAI_API_KEYFallback API key (used when KODE_LLM_API_KEY is not set)
KODE_LLM_ENDPOINTCustom API endpoint (default: https://api.openai.com/v1)
KODE_LLM_MODELDefault model (default: gpt-4o)

​
Relationship to other commands

kode run is a direct alias for kode generate --apply. The two commands are identical in behaviour. Use whichever feels more natural in your workflow.
CommandWhat it does
kode generateGenerate JSON hunks only (does not apply)
kode generate --applyGenerate, verify, and apply — identical to kode run
kode runShortcut for kode generate --apply
kode loopkode run plus test execution and rollback on failure