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 loop is the highest-autonomy command in Kode’s toolkit. Where kode run stops after applying verified patches, kode loop continues through a fifth stage: it executes your test suite, and if tests fail it atomically rolls back every change that was applied in that cycle. Optionally, you can ask Kode to explore the task across multiple parallel Ghost Branch worktrees and automatically merge the best-scoring strategy.

​
What kode loop does differently from kode run

kode run covers three stages: Generate → Verify → Apply. kode loop adds two more:
Stagekode runkode loop
Generate patches via LLM✓✓
Verify hunks through gate✓✓
Apply verified hunks✓✓
Run test suite—✓
Rollback on test failure—✓
Ghost Branch parallelism—✓ (with --branches)
If your test suite passes after apply, the run exits with status PASS and prints a JSON summary to stdout. If the tests fail, Kode restores the repository to the exact snapshot it took before applying — your working tree is left clean.

​
Basic usage

kode loop "implement user deletion endpoint"
Kode auto-detects your test command from the project root (Go → go test ./..., Node → npm test, Rust → cargo test). You can override this with --test-command.

​
All flags

FlagDescriptionDefault
--branches NSpawn N parallel Ghost Branch worktrees, each using a different strategy1 (no Ghost mode)
--modelLLM model overridefrom kode.json
--context-filePath to context packet JSON from kode plan --packetnone
--test-commandTest command overrideauto-detected
--project-dirProject root directorycurrent working directory

​
Ghost Branch mode

When you pass --branches with a value greater than 1, Kode forks the task across N isolated git worktrees running simultaneously. Each worktree applies a different generation strategy:
  • Alpha — lightweight, minimal implementation (smallest surface area)
  • Beta — robust, modular architecture (well-structured, dependency-aware)
  • Gamma — performance-optimised, aggressive (throughput and latency first)
After all branches complete, Kode scores each result on three dimensions — blast radius (files touched), token cost, and wall-clock speed — then merges the winner into your working tree and discards the rest. 
kode loop --branches 3 "refactor the payment service"
Example output: 
── Ghost Branch Mode ────────────────────────────────
  Task: refactor the payment service
  Branches: 3 strategies in parallel
  LLM: anthropic/claude-sonnet-4-6

  [+] alpha (Alpha) — PASS — Score: 0.87 — WINNER
  [x] beta  (Beta)  — PASS — Score: 0.74
  [!] gamma (Gamma) — FAIL — Score: 0.00
      Error: test failure: TestPaymentService/Refund

✓ Winner: alpha (Alpha) — score 0.87
  Total: 18.3s | $0.0042 token cost
Using --branches 2 enables two-strategy mode (Alpha + Beta only). Three strategies (the maximum) give the broadest exploration but roughly triple token cost. Start with --branches 2 and graduate to --branches 3 for complex refactors.

​
Rollback behaviour

If the test suite fails after apply, Kode reverts all changes atomically before exiting. The revert is performed via the internal snapshot mechanism — it does not create a git commit or modify your git history. Your working tree is returned to exactly the state it was in before kode loop ran. The JSON output on a failed run includes the test error message: 
{
  "status": "FAIL",
  "task": "implement user deletion endpoint",
  "hunks_applied": 3,
  "test_error": "FAIL\tgithub.com/example/api [build failed]",
  "duration_seconds": 9.4
}
Loop mode requires a clean git working tree before running. If you have uncommitted changes, Kode will refuse to start — it cannot safely snapshot a dirty tree. Stash or commit your work-in-progress first.

​
Combining kode plan with kode loop

For large or complex tasks, pre-building the context packet with kode plan --packet separates the slow graph-construction step from the generation step. This is especially valuable in Ghost Branch mode, where all three branches would otherwise each build their own context independently. 
# Step 1: build the context packet once
kode plan --packet "refactor auth module" > context.json

# Step 2: run the loop with the pre-built context, 3 branches
kode loop --context-file context.json --branches 3 "refactor auth module"
The --context-file flag accepts the JSON output of kode plan --packet. Kode skips the plan stage entirely and passes the packet directly into the generate stage for every branch.
You can inspect the context packet before using it with cat context.json | jq '.nodes | length' to see how many AST nodes were included. If the number is unexpectedly low, check that the files relevant to your task are tracked in git and that the 8 000-token budget (configurable with kode plan --max-tokens) was not exhausted too early.

​
Configuring the test command

Kode auto-detects the right test command from your project root, but you should configure it explicitly in kode.json for reproducible results: 
{
  "engine": {
    "test_command": "go test -race ./..."
  }
}
Or pass it per-invocation with --test-command: 
kode loop --test-command "make test-integration" "add rate limiting middleware"

​
Next steps

Code Golf

Pit three optimization strategies against each other in parallel and benchmark the winner automatically.

First Task

New to Kode? Start here to initialize your project and run your first task.