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

# Ghost Branches: Parallel AI Strategy Exploration

> Ghost Branches run parallel git worktrees with competing AI strategies, score each result objectively, and merge the winning branch back into your project.

Most AI coding tools pick one approach and run with it. Ghost Branches run several at once. When you activate Ghost Branch mode, Kode creates N isolated git worktrees — each on its own branch, each with its own AI generation pass and full nine-gate verification — and then objectively scores every result. The branch with the best score gets merged into your working directory. The others are silently discarded.

The result is that Kode explores the solution space instead of committing to the first thing the LLM outputs.

## How Ghost Branches work

<Steps />

## How to use Ghost Branches

### In `kode loop`

Pass `--branches N` to `kode loop` to activate Ghost Branch mode for a full Plan → Generate → Verify → Apply → Test cycle. Accepted values are `2` or `3`:

```bash theme={null}
kode loop --branches 3 "add rate limiting to the HTTP API"
```

The terminal output shows each branch, its strategy, its score, and the winner:

```text theme={null}
  [x] alpha (minimal)    — PASS — Score: 0.71
  [+] beta  (modular)    — PASS — Score: 0.84  ← WINNER
  [!] gamma (aggressive) — FAIL — Score: -1.00

  ✓  Winner: beta (modular) — score 0.84
     Total: 34.2s | $0.0031 token cost
```

You can also run two strategies instead of three:

```bash theme={null}
kode loop --branches 2 "refactor the payment module"
```

### In `kode golf`

`kode golf <file>` optimizes a single file using three parallel worktrees, each focused on a different performance dimension:

| Strategy      | Focus                                         |
| ------------- | --------------------------------------------- |
| `concurrency` | Goroutines, channels, async patterns          |
| `memory`      | Pre-allocation, stack vs heap, reduced copies |
| `algorithmic` | Big-O reduction, hash maps, loop elimination  |

```bash theme={null}
kode golf internal/cache/lru.go
```

Kode benchmarks the original code as a baseline with `go test -bench=. -benchmem`, then compares each branch's benchmark results. The branch that most improves the baseline wins. Use `--optimize` to focus on a specific dimension:

```bash theme={null}
kode golf internal/cache/lru.go --optimize memory
```

<Note>
  `kode golf` runs its own fixed set of performance-optimization strategies. It does not use the `--branches` flag — branch count is always 3 in golf mode.
</Note>

## Ghost Branch scoring in detail

Scores are normalized across all branches so the comparison is relative, not absolute. If all three branches have similar blast radii, the blast radius dimension contributes equally to all — the tie-breaker becomes token cost and speed.

A branch that fails verification always scores `-1.0` regardless of other metrics. If all branches fail, Kode selects the one with the least severe error and reports it.

## Best use cases

<CardGroup cols={2}>
  <Card title="Large refactors" icon="code-branch">
    When restructuring a package or extracting a service, you want the approach with the smallest footprint across your codebase. Ghost Branches select the minimal-blast-radius winner automatically.
  </Card>

  <Card title="Performance-sensitive code" icon="gauge">
    Use `kode golf` on hot paths. Three optimization strategies run head-to-head against real benchmarks rather than relying on the LLM's intuition about what will be faster.
  </Card>

  <Card title="Architecture decisions" icon="building">
    When you are genuinely unsure whether to use a modular or minimal approach, Ghost Branches make the tradeoff concrete: you see blast radius, token cost, and test results side-by-side.
  </Card>

  <Card title="Exploratory changes" icon="flask">
    Early in a feature's life, when the right abstraction isn't obvious, run three strategies and see which one passes the most gates and costs the fewest tokens.
  </Card>
</CardGroup>

<Warning>
  Ghost Branches require a **clean git working tree**. If you have uncommitted changes, `git worktree add` will fail because it cannot safely fork from a dirty HEAD. Run `git stash` or commit your work-in-progress before using `--branches`.
</Warning>

## Related pages

* [Guides: Loop mode](/guides/loop-mode) — full walkthrough of the `kode loop` workflow
* [CLI: `kode loop`](/cli/loop) — all flags for the loop command including `--branches`