> ## 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 loop — Full Automated Coding Pipeline with Rollback

> kode loop runs the full Kode workflow: generate, verify, apply, and test — with automatic rollback on test failure. Supports Ghost Branch parallel mode.

`kode loop` is Kode's most complete command. It runs the full workflow in a single invocation: generate patches from a task description, verify each patch through the 9-gate pipeline, apply passing patches to disk, execute your test suite, and automatically roll back to a pre-patch snapshot if tests fail. Use `kode loop` when correctness matters and you want deterministic, test-backed results rather than just structural verification.

## Synopsis

```bash theme={null}
kode loop <task>
```

## What it does

1. **Generate** — sends your task and optional context to the LLM; receives structured JSON hunks.
2. **Verify** — runs each hunk through the 9-gate pipeline (syntax, imports, call graph, architecture, security, blast radius).
3. **Apply** — writes hunks that pass all gates to disk.
4. **Test** — runs your test command (from `.kode/kode.json` or `--test-command`).
5. **Rollback** — if tests fail, restores all modified files from the pre-patch snapshot and exits non-zero.

If tests pass, `kode loop` prints a JSON result to stdout and exits `0`.

## Flags

<ParamField path="--model" type="string">
  Override the LLM model for this run. Accepts `provider/model` format. When omitted, Kode reads from `.kode/kode.json`, then `KODE_LLM_MODEL`, then defaults to `gpt-4o`.

  ```bash theme={null}
  kode loop --model anthropic/claude-sonnet-4-6 "add pagination"
  ```
</ParamField>

<ParamField path="--context-file" type="string">
  Path to a context packet JSON file from `kode plan --packet`. Providing a context packet gives the LLM a focused, token-capped view of relevant files and symbols.

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

<ParamField path="--test-command" type="string">
  Test command to run after applying patches. Overrides the `test_command` in `.kode/kode.json`. If neither is set, Kode auto-detects the command from your project root.

  ```bash theme={null}
  kode loop --test-command "go test ./internal/..." "add user validation"
  ```
</ParamField>

<ParamField path="--project-dir" default="cwd" type="string">
  Project root directory. All file paths and the test command are resolved relative to this directory.
</ParamField>

<ParamField path="--branches" default="1" type="integer">
  Enable Ghost Branch mode by setting this to `2` or `3`. Kode spawns the given number of parallel git worktrees, each using a different implementation strategy, then scores and merges the winner.

  ```bash theme={null}
  kode loop --branches 3 "refactor the caching layer"
  ```
</ParamField>

## Examples

```bash theme={null}
# Standard loop with auto-detected test command
kode loop "add rate limiting to the API handler"

# With a pre-built context packet
kode plan --packet "add pagination" > ctx.json
kode loop --context-file ctx.json "add pagination to user list endpoint"

# Override the test command
kode loop --test-command "pytest tests/unit/" "fix user serialization"

# Ghost Branch mode: run 3 parallel strategies, pick the winner
kode loop --branches 3 "optimize the query builder"
```

## Output

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

```json theme={null}
{
  "status": "PASS",
  "task": "add rate limiting to the API handler",
  "hunks_applied": 2,
  "duration_seconds": 18.4
}
```

On failure (test step exits non-zero), all modified files are rolled back and the output reflects the failure:

```json theme={null}
{
  "status": "FAIL",
  "task": "add rate limiting to the API handler",
  "hunks_applied": 2,
  "test_command": "go test ./...",
  "test_error": "FAIL\tinternal/api [build failed]",
  "duration_seconds": 12.1
}
```

## Ghost Branch mode

When you pass `--branches 2` or `--branches 3`, `kode loop` enters Ghost Branch mode. Each branch runs the full loop in an isolated git worktree using a different implementation strategy:

| Branch | Strategy    | Approach                                  |
| ------ | ----------- | ----------------------------------------- |
| Alpha  | Lightweight | Minimal implementation, smallest diff     |
| Beta   | Robust      | Modular architecture, future-proofed      |
| Gamma  | Aggressive  | Performance-optimized, maximum throughput |

After all branches complete, Kode scores each result by blast radius, token cost, and execution speed, then merges the winning branch into your working tree and discards the rest.

```text theme={null}
── Ghost Branch Mode ────────────────────────────────

  [+] alpha (lightweight)  — PASS — Score: 0.91 — WINNER
  [x] beta  (robust)       — PASS — Score: 0.74
  [!] gamma (aggressive)   — FAIL — Score: 0.00

  ✓  Winner: alpha (lightweight) — score 0.91
  ·  Total: 34.2s | $0.0082 token cost
```

<Warning>
  Ghost Branch mode requires a clean git working tree. Kode creates and destroys temporary worktrees during the run. Uncommitted changes in your working tree are safe — they are not touched — but the repository must be a valid git repo.
</Warning>

## Rollback behaviour

Before applying any patches, `kode loop` snapshots all files that will be modified. If the test step fails, every snapshotted file is restored to its pre-patch state. The snapshot is in-memory; no additional git commits or stashes are created. This means the rollback is instantaneous and leaves no git history.

<Tip>
  Combine `kode plan` with `kode loop` for the best results on multi-file tasks. The context packet helps the LLM make targeted changes, which reduces blast radius and increases the probability of tests passing on the first round.
</Tip>