kode run — Generate and Apply Verified Code Patches

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 9-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

Sends your prompt (plus any context file you provide) to the LLM.
Parses the response into structured hunks — each hunk is a targeted old → new replacement scoped to a single file.
Runs each hunk through the verification pipeline (syntax, imports, call graph, blast radius, architecture, security).
Applies hunks that pass all gates to disk. Hunks that fail are logged with the reason.
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

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"

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"

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

Variable	Description
`KODE_LLM_API_KEY`	API key for the LLM provider (required if not set in provider config)
`OPENAI_API_KEY`	Fallback API key (used when `KODE_LLM_API_KEY` is not set)
`KODE_LLM_ENDPOINT`	Custom API endpoint (default: `https://api.openai.com/v1`)
`KODE_LLM_MODEL`	Default 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.

Command	What it does
`kode generate`	Generate JSON hunks only (does not apply)
`kode generate --apply`	Generate, verify, and apply — identical to `kode run`
`kode run`	Shortcut for `kode generate --apply`
`kode loop`	`kode run` plus test execution and rollback on failure

​Synopsis

​What it does

​Flags

​Examples

​Output

​Environment variables

​Relationship to other commands

Synopsis

What it does

Flags

Examples

Output

Environment variables

Relationship to other commands