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.

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

1
Spin up isolated worktrees
2
Kode calls git worktree add for each branch, creating a separate directory under .kode/ghost/ — for example, .kode/ghost/alpha, .kode/ghost/beta, .kode/ghost/gamma. Each worktree is on its own branch (ghost/alpha, ghost/beta, ghost/gamma) forked from your current HEAD.
3
All worktrees share your repo’s git history and object store, so creation is near-instant regardless of project size.
4
Assign strategies and run in parallel
5
Each worktree receives one of three built-in strategies, each translated into a distinct prompt framing:
6
Branch IDStrategyPrompt focusalphaminimalLightweight, minimal implementation — no extra abstractions, single-file if reasonablebetamodularClean modular architecture — dependency injection, clear interfaces, meaningful abstractionsgammaaggressiveMaximum performance and robustness — caching, async patterns, defensive error handling
7
All three branches run concurrently using a Go goroutine pool. Each one runs a complete pipeline: LLM generation → six-gate verification → test execution. If a branch fails, it automatically retries up to 3 times with an escalating prompt that includes the previous error detail.
8
Score every result
9
Once all branches complete (or time out), Kode scores them using a weighted formula:
10
MetricWeightDirectionBlast radius40%Lower is betterToken cost30%Lower is betterExecution speed20%Faster is betterGates passed10%More is better
11
Any branch that returned FAIL from the verification pipeline receives a score of -1.0 and is excluded from winner selection. If TDD Mode is active, any branch whose tests do not pass is also eliminated before scoring. Only branches that passed all active gates compete for the top score.
12
Merge the winner, clean up the rest
13
Kode calls git worktree remove on every losing branch and deletes its ghost/* git branch. The winning branch’s changes are merged into your current working directory using git merge --squash.
14
You end up with exactly what you would have gotten from a single-strategy run — except the code was chosen from the best of three competing approaches rather than the first thing the LLM produced.

​
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: 
kode loop --branches 3 "add rate limiting to the HTTP API"
The terminal output shows each branch, its strategy, its score, and the winner: 
  [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: 
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:
StrategyFocus
concurrencyGoroutines, channels, async patterns
memoryPre-allocation, stack vs heap, reduced copies
algorithmicBig-O reduction, hash maps, loop elimination
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: 
kode golf internal/cache/lru.go --optimize memory
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.

​
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

Large refactors

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.

Performance-sensitive code

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.

Architecture decisions

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.

Exploratory changes

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