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

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

--model · 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.

kode loop --model anthropic/claude-sonnet-4-6 "add pagination"

--context-file · 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.

kode loop --context-file ctx.json "add pagination to user list"

--test-command · 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.

kode loop --test-command "go test ./internal/..." "add user validation"

--project-dir · string · default: "cwd"

Project root directory. All file paths and the test command are resolved relative to this directory.

--branches · integer · default: "1"

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.

kode loop --branches 3 "refactor the caching layer"

Examples

# 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:

{
  "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:

{
  "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.

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

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.

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.

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.