---
name: codeflash-benchmark
user-invocable: false
disable-model-invocation: true
description: >-
  Run before/after benchmark comparison for a specific change using codeflash compare
  or hyperfine. Activated when the user mentions "benchmark this change",
  "compare performance", "measure speedup", "codeflash compare", "run benchmarks",
  "how much faster", or "verify the improvement".
allowed-tools: "Bash, Read, Write, Grep, Glob"
---

# Benchmark a code change

Compare performance between two git refs using the best available tool.

## Step 1: Determine refs

From the user's request, identify:
- **base ref**: the commit/branch before the change (default: `HEAD~1` or merge-base with main)
- **head ref**: the commit/branch with the change (default: `HEAD`)

## Step 2: Check available tools

```bash
python -m codeflash compare --help 2>/dev/null && echo "CODEFLASH_AVAILABLE" || echo "CODEFLASH_UNAVAILABLE"
which hyperfine 2>/dev/null && echo "HYPERFINE_AVAILABLE" || echo "HYPERFINE_UNAVAILABLE"
```

## Step 3a: codeflash compare (preferred)

If codeflash is available:

```bash
python -m codeflash compare <base_ref> <head_ref> --timeout 120
```

This auto-detects changed functions, creates isolated worktrees, instruments targets with `@codeflash_trace`, and produces per-function nanosecond timings.

## Step 3b: hyperfine fallback

If codeflash is unavailable, use hyperfine:

```bash
hyperfine --warmup 3 \
  "python -c 'import <module>; <benchmark_expr>'" \
  --export-markdown /tmp/bench-results.md
```

## Step 4: Record results

Append the benchmark results to `.codeflash/results.tsv`:

```
<timestamp>\t<base_ref>\t<head_ref>\t<function>\t<before_ns>\t<after_ns>\t<speedup>\tbenchmarked
```

## Step 5: Present results

Show a clean markdown table with:
- Function name
- Before timing
- After timing
- Speedup factor
- Verdict (improvement / regression / neutral)

If any function shows regression, flag it prominently.
