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

# 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

```bash theme={null}
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

<CodeGroup>
  ```bash Default (speed optimization) theme={null}
  kode golf internal/parser/parser.go
  ```

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

  ```bash Algorithmic complexity reduction theme={null}
  kode golf --optimize complexity pkg/search/index.go
  ```

  ```bash TypeScript project with custom benchmark runner theme={null}
  kode golf --test-command "npm run bench" src/parser/index.ts
  ```
</CodeGroup>

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

<Note>
  `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.
</Note>

## Related

* [Ghost Branches concept](/concepts/ghost-branches) — how parallel worktrees work under the hood
* [`kode loop`](/cli/loop) — full pipeline for feature and fix tasks