pgo

PGO — Profile-Guided Optimization

Source: go.dev/doc/pgo (authoritative).

PGO feeds a CPU pprof profile from representative runs of the application back into the compiler for the next build, which uses it to make more informed optimization decisions (e.g. more aggressive inlining of hot functions). As of Go 1.22, representative programs improve ~2–14%. The compiler expects a CPU pprof profile — exactly what runtime/pprof and net/http/pprof produce.

The core rule: the profile must be representative

A profile that is not representative of real behavior yields little or no gain. Microbenchmarks are bad PGO candidates — they exercise a small part of the program. Collect from a representative workload instead. For pi-go that means both of the binary's hot paths, not one:

• The headless agent/tool loop — the tool-coverage eval suite: one pi --mode print scenario per tool family.
• The TUI render loop — RenderMessages, collapseBlankLines, and matchLexer. A live profile attributed ~24% of CPU to the ansi.Strip call blankFast replaces; bubbletea calls View() once per token during streaming, so this is a first-class hot path. It is exercised by the render benchmarks, not by --mode print.

A profile from only one workload optimizes only one half of the program.

How pi-go records a profile

make record-pgo does the whole loop:

1. Builds the binary (make build).
2. Runs the eval-tools suite with PI_EVAL_CPU_PROFILE=tmp/pgo, so every scenario's pi --mode print writes a per-scenario CPU profile via the --cpuprofile flag.
3. Runs the TUI render benchmarks with -cpuprofile tmp/pgo/render.pprof.
4. Merges all profiles into cmd/pi/default.pgo with go tool pprof -proto.
5. Cleans up the scratch profiles.

go build auto-detects default.pgo in the main package directory (cmd/pi/) and enables PGO — no -pgo flag needed. So make build after a record-pgo is a PGO build.