Performance and measurement

Performance is a property of a specific workload and environment. This page publishes one reproducible local snapshot and explains how to extend the same discipline to shell startup, agent hooks, browser workflows, and local models.

Measured handbook build

LOCAL PRODUCTION BUILD

5.56 s median

Apple M3 Max
darwin / arm64 / Node v24.20.0

Captured 2026-09-08. 3 sequential runs; dependencies and Chromium already installed. Other host workloads were not isolated.

HTML payloads from the last measured build

Page	HTML	gzip estimate
/	57.4 KiB	11.7 KiB
/architecture/overview/	68.8 KiB	14.1 KiB
/agents/codex/	52.8 KiB	11.3 KiB
/reference/packages/	168.6 KiB	25.6 KiB
/reference/skills/	77.1 KiB	17.6 KiB
/setup/choose-your-setup/	60.4 KiB	13.6 KiB

These numbers measure local build time and HTML artifacts. CSS, fonts, images, scripts, and search indexes are additional resources. They do not measure browser rendering, network latency, Core Web Vitals, shell startup, or model inference.

Source and method

Revision

f17a5df177af4c3cb6a9ff6ecbaef3af9dbffb7d (working tree modified)

Source fingerprint

28d4500e46cfbd5ea78adcacacc6b07e817d03eae8df399ab37a6611d973d9a6

Method

Three or more sequential local production builds with dependencies and Chromium already installed. The link validator invalidates the content cache on each build. Other host workloads were not isolated. HTML bytes and gzip-9 bytes come from the final measured artifact; gzip values are a transfer-size estimate, not observed HTTP payloads.

Download the measurement JSON

The snapshot records its capture date, Node version, CPU, revision, dirty-worktree status, and a content fingerprint. Run the measurement again after a meaningful implementation or dependency change; it does not update on every documentation edit.

Reproduce the snapshot

npm --prefix site run measure -- --runs 3
./tests/ci.sh docs

The measurement script runs production builds, preserves each build log under site/artifacts/, measures wall-clock duration, and reads the final HTML artifact. It replaces docs/_data/performance.json only after all samples succeed. The final docs gate verifies the newly rendered report.

Keep the browser workload small

• Static HTML carries the article, sidebar, source links, code, tables, and diagrams.
• Mermaid runs during the build and emits inline SVG. Its rendering engine is not shipped to readers.
• Pagefind provides a static search index; there is no search backend to maintain.
• Three local WOFF2 fonts use Latin subsets and font-display: swap; the system font stack supplies missing glyphs.
• WebP screenshots have explicit dimensions and useful alternative text. Diagrams remain vectors.
• Small client scripts handle catalog filters, the command configurator, and image zoom. Catalogs remain readable as complete tables without JavaScript.

These are design decisions, not measured speedup claims. Test transfer size, request behavior, keyboard interaction, and rendering on the deployment and device that matter.

Shell and hook measurements

For shell startup, state whether the shell is login or interactive, whether filesystem and executable caches are warm, and whether the command actually loads the managed profile. A bare zsh -f measurement does not describe the full configured environment.

Agent-hook benchmarks should use representative event payloads. Distinguish no-op events from applicable rules, unchanged files from edits, and cache hits from transcript rescans. The repository already has a comparison harness:

Compare Cursor hook subprocess behavior

# Substitute a real pre-change commit from this repository.
uv run tests/cursor-hook-benchmark.py --baseline PRE_CHANGE_REF

See Agent hook overhead for the scope and cache invariants. Hook subprocess timings are not additive estimates of complete model-response latency.

Local-model measurements

Before comparing model results, record:

1. Model identifier, revision, quantization, license, and runtime version.
2. Hardware, available memory, power mode, and concurrent workloads.
3. Prompt/context size, output limit, tool access, sampling settings, and the actual task.
4. Load time, time to first token, steady generation rate, total elapsed time, peak memory, and task correctness where available.
5. Cold and warm runs, failures, retries, and the number of samples.

Use Local AI coding to establish a working task loop before benchmarking. Token throughput alone does not establish that the model can complete a repository change or use the required tools reliably.

Minimum evidence record

Measurement record shape

{
  "question": "Does this change reduce warm hook latency?",
  "baseline_revision": "actual-before-commit",
  "candidate_revision": "actual-after-commit",
  "environment": "hardware, OS, runtime versions",
  "command": "exact reproducible command",
  "samples": "path to raw measurements",
  "correctness": "path to verifier result",
  "limitations": "unmeasured paths and confounding workloads"
}

This is a schema example, not a benchmark result. Preserve raw observations before reducing them to medians or charts, and retain correctness checks when optimizing.