kode golf — Competitive Code Optimization

kode golf runs three parallel optimization strategies on a source file, benchmarks each against the original, and merges the winning version.

kode golf turns performance tuning into a competitive event. You point it at a source file, and it spins up three isolated git worktrees, each applying a different optimization strategy — concurrency, memory reduction, or algorithmic complexity. Every branch is benchmarked against the original baseline, and Kode merges the winner back into your working tree only if it actually improves performance.

Synopsis

kode golf <file>

<file> is a path to the source file you want optimized, relative to --project-dir (or the current directory).

What it does

1. Baselines — runs the benchmark command against the original file and records ns/op, B/op, and allocs/op for every benchmark function
2. Spawns three worktrees — one per optimization strategy, all running concurrently
3. Generates optimized variants — the configured LLM rewrites the file in each worktree according to the strategy
4. Benchmarks each variant — runs the same benchmark command in each worktree
5. Scores and ranks — compares each result against the baseline and calculates the percentage of benchmarks improved
6. Prompts to merge — displays a ranked leaderboard and asks you to confirm before the winner replaces the original file

If no branch improves on the baseline, kode golf reports the result and leaves the original file untouched.

Flags

Flag	Type	Default	Description
--optimize	string	speed	Optimization target: speed, memory, or complexity
--model	string	from kode.json / KODE_LLM_MODEL	LLM model override
--test-command	string	auto-detected	Benchmark command override (detected from project type if not set)
--project-dir	string	current working directory	Project root

Examples

Default (speed optimization)

kode golf internal/parser/parser.go

Optimization strategies

Each --optimize target instructs the LLM to focus on a different axis of performance:

speed (default)

Focuses on concurrency and throughput — introducing goroutines, channels, async patterns, parallel processing, and batching. Targets elapsed time and ns/op improvements.

memory

Focuses on heap reduction and allocation efficiency — pre-allocating slices and maps, reusing buffers, preferring stack allocation, optimizing struct field alignment, and eliminating unnecessary copies. Targets B/op and allocs/op improvements.

complexity

Focuses on algorithmic Big-O reduction — replacing linear searches with hash maps, eliminating nested loops, using more efficient data structures, and reducing asymptotic work. Targets both time and allocation improvements through better algorithms.

Benchmark output

After all three branches complete, kode golf prints a result table to stderr:

  Baseline — 3 benchmark(s)
    BenchmarkParse: 842.30 ns/op (128 B/op, 3 allocs/op)

  ✓ Alpha (kode-golf-alpha) 👑 WINNER
    Improvement: +3/3 benchmarks (+100%)
    BenchmarkParse: 310.12 ns/op [⬇ 63% faster]

  ✓ Beta (kode-golf-beta)
    Improvement: +2/3 benchmarks (+67%)

  ✗ Gamma (kode-golf-gamma)
    Failed verification

The full JSON summary — including all benchmark numbers — is also written to stdout for scripting.

Merge confirmation

After displaying the leaderboard, kode golf asks:

  Merge optimized version? [Y/n]:

Pressing Enter or typing y applies the winner’s changes. Typing n discards everything and leaves the original file untouched.

kode golf auto-detects your project’s test command based on project type (go test ./... for Go, npm test for Node, cargo test for Rust). The auto-detected command runs the full test suite, not a dedicated benchmark. To measure benchmark performance, pass --test-command explicitly with a benchmark-enabled command — for example go test -bench=. -benchmem ./... for Go or npm run bench for Node. The output parser expects benchmark results in the format BenchmarkFoo N X ns/op. If your runner uses a different format, results will still display but delta calculations may be skipped.

Related

• Ghost Branches concept — how parallel worktrees work under the hood
• kode loop — full pipeline for feature and fix tasks