> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trykode.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# kode run — Generate and Apply Verified Code Patches

> kode run generates code from a prompt, passes it through Kode's 9-gate verification pipeline, and applies verified patches to your codebase in one step.

`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

```bash theme={null}
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.

<Note>
  `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`](/cli/loop).
</Note>

## Flags

<ParamField path="--model" type="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`.

  ```bash theme={null}
  kode run --model openai/gpt-4o "refactor the auth module"
  ```
</ParamField>

<ParamField path="--context-file" type="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.

  ```bash theme={null}
  kode run --context-file context.json "add pagination to the user list"
  ```
</ParamField>

<ParamField path="--project-dir" default="cwd" type="string">
  Project root directory. Kode resolves all file paths relative to this directory. Defaults to the current working directory.
</ParamField>

## Examples

```bash theme={null}
# 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"
```

<Info>
  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.
</Info>

## Output

On success, `kode run` prints a JSON summary to stdout:

```json theme={null}
{
  "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 |